Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-17 00:24:10 +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.

75
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,25 +30,43 @@ paths:
operationId: ping
security:
- homeserverAccessToken: []
parameters:
- in: body
name: body
description: Ping body with optional transaction ID.
schema:
type: object
example: {
"transaction_id": "mautrix-go_1683636478256400935_123"
}
properties:
transaction_id:
type: string
description: |-
A transaction ID for the ping, copied directly from the
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
requestBody:
content:
application/json:
schema:
type: object
example: {
"transaction_id": "mautrix-go_1683636478256400935_123"
}
properties:
transaction_id:
type: string
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: {}
schema:
type: object
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

395
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"
responses:
200:
description: The protocol was found and metadata returned.
example: irc
schema:
$ref: definitions/protocol.yaml
401:
type: string
responses:
"200":
description: The protocol was found and metadata returned.
content:
application/json:
schema:
$ref: definitions/protocol.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/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.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: definitions/user_batch.yaml
401:
type: string
responses:
"200":
description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/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.
responses:
200:
description: At least one portal room was found.
schema:
$ref: definitions/location_batch.yaml
401:
type: string
responses:
"200":
description: At least one portal room was found.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/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.
responses:
200:
description: |-
All found third-party locations.
schema:
$ref: definitions/location_batch.yaml
401:
type: string
responses:
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/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.
responses:
200:
description: |-
An array of third-party users.
schema:
$ref: definitions/user_batch.yaml
401:
type: string
responses:
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
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

104
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: {}
schema:
type: object
401:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
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

104
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: {}
schema:
type: object
401:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
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

89
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: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member.yaml"},
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
]
}
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
$ref: "../client-server/definitions/client_event.yaml"
required: ["events"]
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"
}
]
}
properties:
events:
type: array
description: A list of events, formatted as per the Client-Server API.
items:
$ref: ../client-server/definitions/client_event.yaml
required:
- events
description: Transaction information
responses:
200:
"200":
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object
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

395
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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
- in: body
name: content
required: true
description: |-
The content of the account data.
example: org.example.custom.config
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"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: {}
schema:
type: object
400:
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
The request body is not a JSON object. Errcode: `M_BAD_JSON`
or `M_NOT_JSON`.
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"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."
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
responses:
200:
description:
The account data content for the given type.
example: org.example.custom.config
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
403:
type: string
responses:
"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":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"404":
description: |-
No account data has been provided for this user with the given `type`.
Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to set account data on.
x-example: "!726s6s6q:example.com"
description: The ID of the room to set account data on.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
- in: body
name: content
required: true
description: |-
The content of the account data.
example: org.example.custom.room.config
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"}
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"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: {}
schema:
type: object
400:
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
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`).
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$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:
@ -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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to get account data for.
x-example: "!726s6s6q:example.com"
description: The ID of the room to get account data for.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
responses:
200:
description:
The account data content for the given type.
example: org.example.custom.room.config
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`.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
403:
type: string
responses:
"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`."
content:
application/json:
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
"403":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"404":
description: |-
No account data has been provided for this user and this room with the
given `type`. Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
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

156
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,75 +30,94 @@ 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.
examples:
application/json: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"connections": [
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:
response:
value: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
"connections": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
}
]
}
]
}
]
}
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: |-
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
tags:
- Server administration
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

735
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,48 +33,56 @@ 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
}
]
}
schema:
type: object
properties:
threepids:
type: array
items:
type: object
title: Third-party identifier
properties:
medium:
type: string
description: The medium of the third-party identifier.
enum: ["email", "msisdn"]
address:
type: string
description: The third-party identifier address.
validated_at:
type: integer
format: int64
description: |-
The timestamp, in milliseconds, when the identifier was
validated by the identity server.
added_at:
type: integer
format: int64
description:
The timestamp, in milliseconds, when the homeserver
associated the third-party identifier with the user.
required: ['medium', 'address', 'validated_at', 'added_at']
content:
application/json:
schema:
type: object
properties:
threepids:
type: array
items:
type: object
title: Third-party identifier
properties:
medium:
type: string
description: The medium of the third-party identifier.
enum:
- email
- msisdn
address:
type: string
description: The third-party identifier address.
validated_at:
type: integer
format: int64
description: |-
The timestamp, in milliseconds, when the identifier was
validated by the identity server.
added_at:
type: integer
format: int64
description: The timestamp, in milliseconds, when the homeserver associated the
third-party identifier with the user.
required:
- medium
- address
- validated_at
- added_at
examples:
response:
value: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
tags:
- Account management
post:
@ -105,36 +102,40 @@ paths:
deprecated: true
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
three_pid_creds:
title: "ThreePidCredentials"
type: object
description: The third-party credentials to associate with the account.
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
required: ["three_pid_creds"]
example: {
requestBody:
content:
application/json:
schema:
type: object
properties:
three_pid_creds:
title: ThreePidCredentials
type: object
description: The third-party credentials to associate with the account.
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required:
- client_secret
- id_server
- id_access_token
- sid
required:
- three_pid_creds
example: {
"three_pid_creds": {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
@ -142,45 +143,52 @@ 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"
}
schema:
type: object
properties:
submit_url:
type: string
format: uri
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's `POST
/validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
content:
application/json:
schema:
type: object
properties:
submit_url:
type: string
format: uri
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's `POST
/validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the `/versions` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
403:
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the `/versions` response (ie: r0.5.0).
example: https://example.org/path/to/submitToken
examples:
response:
value: {
"submit_url": "https://example.org/path/to/submitToken"
}
"403":
description: The credentials could not be verified with the identity server.
examples:
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third-party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
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."
}
tags:
- Account management
"/account/3pid/add":
/account/3pid/add:
post:
summary: Adds contact information to the user's account.
description: |-
@ -194,47 +202,55 @@ paths:
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
example: "d0nt-T3ll"
sid:
type: string
description: The session identifier given by the homeserver.
example: "abc123987"
required: ["client_secret", "sid"]
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: definitions/auth_data.yaml
client_secret:
type: string
description: The client secret used in the session with the homeserver.
example: d0nt-T3ll
sid:
type: string
description: The session identifier given by the homeserver.
example: abc123987
required:
- client_secret
- sid
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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,47 +264,55 @@ paths:
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0nt-T3ll"
}
requestBody:
content:
application/json:
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required:
- client_secret
- id_server
- id_access_token
- sid
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0nt-T3ll"
}
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
429:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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,59 +325,63 @@ paths:
operationId: delete3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
requestBody:
content:
application/json:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The homeserver has disassociated the third-party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. `success` indicates that the
identity server has unbound the identifier whereas `no-support`
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- 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
identity server has unbound the identifier whereas `no-support`
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: success
required:
- id_server_unbind_result
tags:
- Account management
"/account/3pid/unbind":
/account/3pid/unbind:
post:
summary: Removes a user's third-party identifier from an identity server.
description: |-
@ -366,60 +394,65 @@ paths:
operationId: unbind3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
requestBody:
content:
application/json:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The identity server has disassociated the third-party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: "success"
required:
- id_server_unbind_result
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- no-support
- success
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: success
required:
- id_server_unbind_result
tags:
- 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
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$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.
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:
content:
application/json:
schema:
$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.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
200:
"200":
description: An SMS message was sent to the given phone number.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
content:
application/json:
schema:
$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.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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

232
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,63 +35,79 @@ 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: 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"
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
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
"200":
description: The ping was successful.
schema:
type: object
properties:
duration_ms:
type: integer
description: |-
The duration in milliseconds that the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
request took from the homeserver's point of view.
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`.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"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`.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Provided access token is not the appservice's as_token"
}
502:
content:
application/json:
schema:
type: object
properties:
duration_ms:
type: integer
description: |-
The duration in milliseconds that the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
request took from the homeserver's point of view.
required:
- duration_ms
examples:
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
examples:
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`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Provided access token is not the appservice's as_token"
}
"502":
description: |-
The application service returned a bad status, or the connection failed.
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
@ -112,41 +115,68 @@ paths:
For bad statuses, the response may include `status` and `body`
fields containing the HTTP status code and response body text
respectively to aid with debugging.
schema:
type: object
title: Error
description: A Matrix-level Error
properties:
errcode:
type: string
description: An error code.
enum: [M_BAD_STATUS, M_CONNECTION_FAILED]
error:
type: string
description: A human-readable error message.
example: Ping returned status 401
status:
type: integer
description: The HTTP status code returned by the appservice.
example: 401
body:
type: string
description: The HTTP response body returned by the appservice.
example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
required: ["errcode"]
examples:
application/json: {
"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`.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_CONNECTION_TIMEOUT",
"error": "Connection to application service timed out"
}
content:
application/json:
schema:
type: object
title: Error
description: A Matrix-level Error
properties:
errcode:
type: string
description: An error code.
enum:
- M_BAD_STATUS
- M_CONNECTION_FAILED
error:
type: string
description: A human-readable error message.
example: Ping returned status 401
status:
type: integer
description: The HTTP status code returned by the appservice.
example: 401
body:
type: string
description: The HTTP response body returned by the appservice.
example: '{"errcode": "M_UNKNOWN_TOKEN"}'
required:
- errcode
examples:
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`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_CONNECTION_TIMEOUT",
"error": "Connection to application service timed out"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

92
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"
example: irc
schema:
type: string
- in: path
type: string
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:example.org"
- in: body
name: body
required: true
example: "!somewhere:example.org"
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum:
- public
- private
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: public
required:
- visibility
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.
schema:
type: object
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
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

186
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,51 +30,60 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being banned.
reason:
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"]
properties:
user_id:
type: string
description: The fully qualified user ID of the user being banned.
reason:
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
required: true
responses:
200:
"200":
description: The user has been kicked and banned from the room.
examples:
application/json: {
}
schema:
type: object
403:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags:
- Room membership
"/rooms/{roomId}/unban":
@ -101,50 +99,74 @@ 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: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "They've been banned long enough"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "They've been banned long enough"
}
schema:
type: object
403:
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required: true
responses:
"200":
description: The user has been unbanned from the room.
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
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

169
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,79 +25,99 @@ paths:
operationId: getCapabilities
security:
- accessToken: []
parameters: []
responses:
200:
description:
The capabilities of the server.
examples:
application/json: {
"capabilities": {
"m.change_password": {
"enabled": false
},
"m.room_versions": {
"default": "1",
"available": {
"1": "stable",
"2": "stable",
"3": "unstable",
"test-version": "unstable"
}
},
"com.example.custom.ratelimit": {
"max_requests_per_hour": 600
}
}
}
schema:
type: object
required: ["capabilities"]
properties:
capabilities:
"200":
description: The capabilities of the server.
content:
application/json:
schema:
type: object
title: Capabilities
description: |-
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
required:
- capabilities
properties:
"m.change_password":
capabilities:
type: object
title: Capabilities
description: |-
Capability to indicate if the user can change their password.
title: ChangePasswordCapability
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
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:
m.change_password:
type: object
description: |-
A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum: [stable, unstable]
description: The stability of the room version.
required: ['default', 'available']
429:
description: 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:
response:
value: {
"capabilities": {
"m.change_password": {
"enabled": false
},
"m.room_versions": {
"default": "1",
"available": {
"1": "stable",
"2": "stable",
"3": "unstable",
"test-version": "unstable"
}
},
"com.example.custom.ratelimit": {
"max_requests_per_hour": 600
}
}
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

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

File diff suppressed because it is too large Load diff

377
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,175 +65,190 @@ paths:
operationId: createRoom
security:
- accessToken: []
parameters:
- in: body
name: body
description: The desired room configuration.
required: true
schema:
type: object
example: {
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
requestBody:
content:
application/json:
schema:
type: object
example: {
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
}
}
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
A `public` visibility indicates that the room will be shown
in the published room list. A `private` visibility will hide
the room from the published room list. Rooms default to
`private` visibility if this key is not included. NB: This
should not be confused with `join_rules` which also uses the
word `public`.
room_alias_name:
type: string
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be `#foo:example.com`.
The complete room alias will become the canonical alias for
the room and an `m.room.canonical_alias` event will be sent
into the room.
name:
type: string
description: |-
If this is included, an `m.room.name` event will be sent
into the room to indicate the name of the room. See Room
Events for more information on `m.room.name`.
topic:
type: string
description: |-
If this is included, an `m.room.topic` event will be sent
into the room to indicate the topic for the room. See Room
Events for more information on `m.room.topic`.
invite:
type: array
description: |-
A list of user IDs to invite to the room. This will tell the
server to invite everyone in the list to the newly created room.
items:
properties:
visibility:
type: string
invite_3pid:
type: array
description: |-
A list of objects representing third-party IDs to invite into
the room.
items:
type: object
title: Invite3pid
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example `email`
(see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not
support the room version.
example: "1"
creation_content:
title: CreationContent
type: object
description: |-
Extra keys, such as `m.federate`, to be added to the content
of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following
keys: `creator`, `room_version`. Future versions of the specification
may allow the server to overwrite other keys.
initial_state:
type: array
description: |-
A list of state events to set in the new room. This allows
the user to override the default state events set in the new
room. The expected format of the state events are an object
with type, state_key and content keys set.
enum:
- public
- private
description: |-
A `public` visibility indicates that the room will be shown
in the published room list. A `private` visibility will hide
the room from the published room list. Rooms default to
`private` visibility if this key is not included. NB: This
should not be confused with `join_rules` which also uses the
word `public`.
room_alias_name:
type: string
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be `#foo:example.com`.
Takes precedence over events set by `preset`, but gets
overridden by `name` and `topic` keys.
items:
The complete room alias will become the canonical alias for
the room and an `m.room.canonical_alias` event will be sent
into the room.
name:
type: string
description: |-
If this is included, an `m.room.name` event will be sent
into the room to indicate the name of the room. See Room
Events for more information on `m.room.name`.
topic:
type: string
description: |-
If this is included, an `m.room.topic` event will be sent
into the room to indicate the topic for the room. See Room
Events for more information on `m.room.topic`.
invite:
type: array
description: |-
A list of user IDs to invite to the room. This will tell the
server to invite everyone in the list to the newly created room.
items:
type: string
invite_3pid:
type: array
description: |-
A list of objects representing third-party IDs to invite into
the room.
items:
type: object
title: Invite3pid
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example `email`
(see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required:
- id_server
- id_access_token
- medium
- address
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not
support the room version.
example: "1"
creation_content:
title: CreationContent
type: object
title: StateEvent
properties:
type:
type: string
description: The type of event to send.
state_key:
type: string
description: The state_key of the state event. Defaults to an empty string.
content:
type: object
description: The content of the event.
required: ["type", "content"]
preset:
type: string
enum: ["private_chat", "public_chat", "trusted_private_chat"]
description: |-
Convenience parameter for setting various default state events
based on a preset.
description: |-
Extra keys, such as `m.federate`, to be added to the content
of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following
keys: `creator`, `room_version`. Future versions of the specification
may allow the server to overwrite other keys.
initial_state:
type: array
description: |-
A list of state events to set in the new room. This allows
the user to override the default state events set in the new
room. The expected format of the state events are an object
with type, state_key and content keys set.
If unspecified, the server should use the `visibility` to determine
which preset to use. A visbility of `public` equates to a preset of
`public_chat` and `private` visibility equates to a preset of
`private_chat`.
is_direct:
type: boolean
description: |-
This flag makes the server set the `is_direct` flag on the
`m.room.member` events sent to the users in `invite` and
`invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
power_level_content_override:
title: Power Level Event Content
type: object
description: |-
The power level content to override in the default power level
event. This object is applied on top of the generated
[`m.room.power_levels`](/client-server-api/#mroompower_levels)
event content prior to it being sent to the room. Defaults to
overriding nothing.
Takes precedence over events set by `preset`, but gets
overridden by `name` and `topic` keys.
items:
type: object
title: StateEvent
properties:
type:
type: string
description: The type of event to send.
state_key:
type: string
description: The state_key of the state event. Defaults to an empty string.
content:
type: object
description: The content of the event.
required:
- type
- content
preset:
type: string
enum:
- private_chat
- public_chat
- trusted_private_chat
description: |-
Convenience parameter for setting various default state events
based on a preset.
If unspecified, the server should use the `visibility` to determine
which preset to use. A visbility of `public` equates to a preset of
`public_chat` and `private` visibility equates to a preset of
`private_chat`.
is_direct:
type: boolean
description: |-
This flag makes the server set the `is_direct` flag on the
`m.room.member` events sent to the users in `invite` and
`invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
power_level_content_override:
title: Power Level Event Content
type: object
description: |-
The power level content to override in the default power level
event. This object is applied on top of the generated
[`m.room.power_levels`](/client-server-api/#mroompower_levels)
event content prior to it being sent to the room. Defaults to
overriding nothing.
description: The desired room configuration.
required: true
responses:
200:
"200":
description: Information about the newly created room.
schema:
type: object
description: Information about the newly created room.
properties:
room_id:
type: string
description: |-
The created room's ID.
required: ['room_id']
examples:
application/json: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
400:
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
examples:
response:
value: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
"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.
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$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

363
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,87 +27,93 @@ paths:
operationId: uploadCrossSigningKeys
security:
- accessToken: []
parameters:
- in: body
name: keys
description: |-
The keys to be published.
required: true
schema:
type: object
properties:
master_key:
description: |-
Optional. The user\'s master key.
allOf:
- $ref: definitions/cross_signing_key.yaml
self_signing_key:
description: |-
Optional. The user\'s self-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
user_signing_key:
description: |-
Optional. The user\'s user-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
example: {
"auth": {
"type": "example.type.foo",
"session": "xxxxx",
"example_credential": "verypoorsharedsecret"
},
"master_key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
}
},
"self_signing_key": {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
requestBody:
content:
application/json:
schema:
type: object
properties:
master_key:
description: Optional. The user\'s master key.
allOf:
- $ref: definitions/cross_signing_key.yaml
self_signing_key:
description: |-
Optional. The user\'s self-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
user_signing_key:
description: |-
Optional. The user\'s user-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: definitions/auth_data.yaml
example: {
"auth": {
"type": "example.type.foo",
"session": "xxxxx",
"example_credential": "verypoorsharedsecret"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
"master_key": {
"user_id": "@alice:example.com",
"usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
}
}
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
"self_signing_key": {
"user_id": "@alice:example.com",
"usage": [
"self_signing"
],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
}
}
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": [
"user_signing"
],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
}
}
}
}
}
description: The keys to be published.
required: true
responses:
200:
"200":
description: The provided keys were successfully uploaded.
schema:
type: object
example: {}
400:
content:
application/json:
schema:
type: object
example: {}
"400":
description: |-
The input was invalid in some way. This can include one of the
following error codes:
@ -126,25 +121,29 @@ 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.
schema:
type: object
example: {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
403:
content:
application/json:
schema:
type: object
example: {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
"403":
description: |-
The public key of one of the keys is the same as one of the user\'s
device IDs, or the request is not authorized for any other reason.
schema:
type: object
example: {
"errcode": "M_FORBIDDEN",
"error": "Key ID in use"
}
content:
application/json:
schema:
type: object
example: {
"errcode": "M_FORBIDDEN",
"error": "Key ID in use"
}
tags:
- End-to-end encryption
"/keys/signatures/upload":
/keys/signatures/upload:
post:
x-addedInMatrixVersion: "1.1"
summary: Upload cross-signing signatures.
@ -158,91 +157,109 @@ 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
schema:
type: object
title: Signatures
additionalProperties:
requestBody:
content:
application/json:
schema:
type: object
title: Signatures
additionalProperties:
type: object
example: {
"@alice:example.com": {
"HIJKLMN": {
"user_id": "@alice:example.com",
"device_id": "HIJKLMN",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"keys": {
"curve25519:HIJKLMN": "base64+curve25519+key",
"ed25519:HIJKLMN": "base64+ed25519+key"
additionalProperties:
type: object
example: {
"@alice:example.com": {
"HIJKLMN": {
"user_id": "@alice:example.com",
"device_id": "HIJKLMN",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"keys": {
"curve25519:HIJKLMN": "base64+curve25519+key",
"ed25519:HIJKLMN": "base64+ed25519+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
}
}
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
"base64+master+public+key": {
"user_id": "@alice:example.com",
"usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:HIJKLMN": "base64+signature+of+master+key"
}
}
}
},
"base64+master+public+key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:HIJKLMN": "base64+signature+of+master+key"
}
}
}
},
"@bob:example.com": {
"bobs+base64+master+public+key": {
"user_id": "@bob:example.com",
"keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
},
"usage": ["master"],
"signatures": {
"@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
"@bob:example.com": {
"bobs+base64+master+public+key": {
"user_id": "@bob:example.com",
"keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
},
"usage": [
"master"
],
"signatures": {
"@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
}
}
}
}
}
}
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.
schema:
type: object
properties:
failures:
content:
application/json:
schema:
type: object
description: |-
A map from user ID to key ID to an error for any signatures
that failed. If a signature was invalid, the `errcode` will
be set to `M_INVALID_SIGNATURE`.
additionalProperties:
type: object
additionalProperties:
properties:
failures:
type: object
title: Error
example: {
"@alice:example.com": {
"HIJKLMN": {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
}
}
description: |-
A map from user ID to key ID to an error for any signatures
that failed. If a signature was invalid, the `errcode` will
be set to `M_INVALID_SIGNATURE`.
additionalProperties:
type: object
additionalProperties:
type: object
title: Error
example:
"@alice:example.com":
HIJKLMN:
errcode: M_INVALID_SIGNATURE
error: Invalid signature
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.

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

@ -11,126 +11,124 @@
# 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
schema:
type: object
properties:
devices:
type: array
description: A list of all registered devices for this user.
items:
type: object
allOf:
- $ref: "definitions/client_device.yaml"
examples:
application/json: {
"devices": [
{
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
content:
application/json:
schema:
type: object
properties:
devices:
type: array
description: A list of all registered devices for this user.
items:
type: object
allOf:
- $ref: definitions/client_device.yaml
examples:
response:
value: {
"devices": [
{
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
]
}
]
}
tags:
- Device management
"/devices/{deviceId}":
get:
summary: Get a single device
description: |-
Gets information on a single device, by device id.
description: Gets information on a single device, by device id.
operationId: getDevice
security:
- accessToken: []
parameters:
- in: path
type: string
name: deviceId
description: The device to retrieve.
required: true
x-example: "QBUAZIFURK"
responses:
200:
description: Device information
example: QBUAZIFURK
schema:
type: object
allOf:
- $ref: "definitions/client_device.yaml"
examples:
application/json: {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
404:
type: string
responses:
"200":
description: Device information
content:
application/json:
schema:
type: object
allOf:
- $ref: definitions/client_device.yaml
examples:
response:
value: {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
"404":
description: The current user has no device with the given ID.
tags:
- Device management
put:
summary: Update a device
description: |-
Updates the metadata on the given device.
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: object
properties:
display_name:
type: string
description: |-
The new display name for this device. If not given, the
display name is unchanged.
example: { "display_name": "My other phone" }
responses:
200:
description: The device was successfully updated.
examples:
application/json: {
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
display_name:
type: string
description: |-
The new display name for this device. If not given, the
display name is unchanged.
example: {
"display_name": "My other phone"
}
schema:
type: object # empty json object
404:
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
examples:
response:
value: {}
"404":
description: The current user has no device with the given ID.
tags:
- Device management
@ -145,41 +143,46 @@ 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: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: definitions/auth_data.yaml
required: true
responses:
200:
"200":
description: |-
The device was successfully removed, or had been removed
previously.
schema:
type: object
examples:
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
tags:
- Device management
"/delete_devices":
/delete_devices:
post:
summary: Bulk deletion of devices
description: |-
@ -189,42 +192,62 @@ paths:
operationId: deleteDevices
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
devices:
type: array
description: The list of device IDs to delete.
items:
type: string
description: A list of device IDs.
example: ["QBUAZIFURK", "AUIECTSRND"]
auth:
allOf:
- "$ref": "definitions/auth_data.yaml"
description: |-
requestBody:
content:
application/json:
schema:
type: object
properties:
devices:
type: array
description: The list of device IDs to delete.
items:
type: string
description: A list of device IDs.
example:
- QBUAZIFURK
- AUIECTSRND
auth:
allOf:
- $ref: definitions/auth_data.yaml
description: |-
Additional authentication information for the
user-interactive authentication API.
required:
- devices
required:
- devices
required: true
responses:
200:
"200":
description: |-
The devices were successfully removed, or had been removed
previously.
schema:
type: object
examples:
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$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

344
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: object
properties:
room_id:
type: string
description: The room ID to set.
required: ['room_id']
example: {
"room_id": "!abnjk1jdasj98:capuchins.com"
}
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The room ID to set.
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: {}
schema:
type: object
400:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: The given `roomAlias` is not a valid room alias.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
schema:
"$ref": "definitions/errors/error.yaml"
409:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
"409":
description: A room alias with that name already exists.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
tags:
- Room directory
get:
@ -91,59 +92,68 @@ 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.
schema:
type: object
properties:
room_id:
type: string
description: The room ID for this room alias.
servers:
type: array
description: A list of servers that are aware of this room alias.
items:
type: string
description: A server which is aware of this room alias.
examples:
application/json: {
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
"matrix.org",
"another.com"
]
}
400:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The room ID for this room alias.
servers:
type: array
description: A list of servers that are aware of this room alias.
items:
type: string
description: A server which is aware of this room alias.
examples:
response:
value: {
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
"matrix.org",
"another.com"
]
}
"400":
description: The given `roomAlias` is not a valid room alias.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
"404":
description: There is no mapped room ID for this room alias.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
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: {
}
schema:
type: object
404:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: There is no mapped room ID for this room alias.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
tags:
- Room directory
"/rooms/{roomId}/aliases":
@ -212,59 +227,86 @@ 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"
]
}
schema:
type: object
properties:
aliases:
type: array
description: The server's local aliases on the room. Can be empty.
items:
type: string
required: ['aliases']
400:
"200":
description: The list of local aliases for the room.
content:
application/json:
schema:
type: object
properties:
aliases:
type: array
description: The server's local aliases on the room. Can be empty.
items:
type: string
required:
- aliases
examples:
response:
value: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
"400":
description: The given `roomAlias` is not a valid room alias.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "Room alias invalid"
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: The user is not permitted to retrieve the list of local aliases for the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not a member of the room."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
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
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not a member of the room."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

193
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"
example: "!636q39766251:example.com"
schema:
type: string
- in: path
type: string
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,78 +64,94 @@ paths:
homeserver prefers.
See [Filtering](/client-server-api/#filtering) for more information.
x-example: "66696p746572"
responses:
200:
description: The events and state surrounding the requested event.
example: 66696p746572
schema:
type: object
description: The events and state surrounding the requested event.
properties:
start:
type: string
description: |-
A token that can be used to paginate backwards with.
end:
type: string
description: |-
A token that can be used to paginate forwards with.
events_before:
type: array
description: |-
A list of room events that happened just before the
requested event, in reverse-chronological order.
items:
$ref: "definitions/client_event.yaml"
event:
description: |-
Details of the requested event.
allOf:
- $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"
state:
type: array
description: |-
The state of the room at the last event returned.
items:
$ref: "definitions/client_event.yaml"
examples:
application/json: {
"end": "t29-57_2_0_2",
"events_after": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
],
"event": {
"event_id": "$f3h4d129462ha:example.com",
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.image.yaml"
},
"events_before": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
}
type: string
responses:
"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.
end:
type: string
description: A token that can be used to paginate forwards with.
events_before:
type: array
description: |-
A list of room events that happened just before the
requested event, in reverse-chronological order.
items:
$ref: definitions/client_event.yaml
event:
description: Details of the requested event.
allOf:
- $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
state:
type: array
description: The state of the room at the last event returned.
items:
$ref: definitions/client_event.yaml
examples:
response:
value: {
"end": "t29-57_2_0_2",
"events_after": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
],
"event": {
"event_id": "$f3h4d129462ha:example.com",
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.image.yaml"
},
"events_before": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
}
tags:
- Room participation
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

267
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,61 +28,90 @@ 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: object
allOf:
- $ref: "definitions/sync_filter.yaml"
example: {
"room": {
"state": {
"types": ["m.room.*"],
"not_rooms": ["!726s6s6q:example.com"]
type: string
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: definitions/sync_filter.yaml
example: {
"room": {
"state": {
"types": [
"m.room.*"
],
"not_rooms": [
"!726s6s6q:example.com"
]
},
"timeline": {
"limit": 10,
"types": [
"m.room.message"
],
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
]
},
"ephemeral": {
"types": [
"m.receipt",
"m.typing"
],
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
]
}
},
"timeline": {
"limit": 10,
"types": ["m.room.message"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
"presence": {
"types": [
"m.presence"
],
"not_senders": [
"@alice: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"]
}
"event_format": "client",
"event_fields": [
"type",
"content",
"sender"
]
}
description: The filter to upload.
required: true
responses:
200:
"200":
description: The filter was created.
schema:
type: object
properties:
filter_id:
type: string
description: |-
The ID of the filter that was created. Cannot start
with a `{` as this character is used to determine
if the filter provided is inline JSON or a previously
declared filter by homeservers on some APIs.
example: "66696p746572"
required: ['filter_id']
content:
application/json:
schema:
type: object
properties:
filter_id:
type: string
description: |-
The ID of the filter that was created. Cannot start
with a `{` as this character is used to determine
if the filter provided is inline JSON or a previously
declared filter by homeservers on some APIs.
example: 66696p746572
required:
- filter_id
tags:
- Room participation
"/user/{userId}/filter/{filterId}":
@ -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
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"]
}
example: 66696p746572
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.yaml"
404:
description: "Unknown filter."
type: string
responses:
"200":
description: The filter definition.
content:
application/json:
schema:
type: object
allOf:
- $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

128
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,46 +36,51 @@ 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: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "Welcome to the team!"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the invitee.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been invited to join the room, or was already invited to the room.
examples:
application/json: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "Welcome to the team!"
}
schema:
type: object
400:
properties:
user_id:
type: string
description: The fully qualified user ID of the invitee.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required: true
responses:
"200":
description: The user has been invited to join the room, or was already invited
to the room.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
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.
schema:
"$ref": "definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
"403":
description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
@ -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.
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

235
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,48 +36,55 @@ 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: object
properties:
third_party_signed:
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If supplied, the homeserver must verify that it matches a pending
`m.room.third_party_invite` event in the room, and perform
key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
third_party_signed:
allOf:
- $ref: definitions/third_party_signed.yaml
description: |-
If supplied, the homeserver must verify that it matches a pending
`m.room.third_party_invite` event in the room, and perform
key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
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"}
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Room membership
"/join/{roomIdOrAlias}":
@ -126,57 +129,67 @@ 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: object
properties:
third_party_signed:
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If a `third_party_signed` was supplied, the homeserver must verify
that it matches a pending `m.room.third_party_invite` event in the
room, and perform key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
third_party_signed:
allOf:
- $ref: definitions/third_party_signed.yaml
description: |-
If a `third_party_signed` was supplied, the homeserver must verify
that it matches a pending `m.room.third_party_invite` event in the
room, and perform key validity checking if required by the event.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
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"}
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

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

File diff suppressed because it is too large Load diff

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

@ -13,414 +13,365 @@
# 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
schema:
type: object
properties:
device_keys:
description: |-
Identity keys for the device. May be absent if no new
identity keys are required.
allOf:
- $ref: definitions/device_keys.yaml
one_time_keys:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
type: object
title: OneTimeKeys
description: |-
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
`<algorithm>:<key_id>`. The format of the key is determined
by the [key algorithm](/client-server-api/#key-algorithms).
requestBody:
content:
application/json:
schema:
type: object
properties:
device_keys:
description: |-
Identity keys for the device. May be absent if no new
identity keys are required.
allOf:
- $ref: definitions/device_keys.yaml
one_time_keys:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
type: object
title: OneTimeKeys
description: |-
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
`<algorithm>:<key_id>`. The format of the key is determined
by the [key algorithm](/client-server-api/#key-algorithms).
May be absent if no new one-time keys are required.
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"
# XXX: We can't define an actual object here - see above.
type: object
title: OneTimeKeys
description: |-
The public key which should be used if the device's one-time keys
are exhausted. The fallback key is not deleted once used, but should
be replaced when additional one-time keys are being uploaded. The
server will notify the client of the fallback key being used through
`/sync`.
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
fallback_keys:
x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here - see above.
type: object
title: OneTimeKeys
description: |-
The public key which should be used if the device's one-time keys
are exhausted. The fallback key is not deleted once used, but should
be replaced when additional one-time keys are being uploaded. The
server will notify the client of the fallback key being used through
`/sync`.
There can only be at most one key per algorithm uploaded, and the server
will only persist one key per algorithm.
There can only be at most one key per algorithm uploaded, and the server
will only persist one key per algorithm.
When uploading a signed key, an additional `fallback: true` key should
be included to denote that the key is a fallback key.
When uploading a signed key, an additional `fallback: true` key should
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"
}
}
}
}
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
description: The keys to be published
required: true
responses:
200:
description:
The provided keys were successfully uploaded.
schema:
type: object
properties:
one_time_key_counts:
"200":
description: The provided keys were successfully uploaded.
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
description: |-
For each key algorithm, the number of unclaimed one-time keys
of that type currently held on the server for this device.
If an algorithm is not listed, the count for that algorithm
is to be assumed zero.
example:
curve25519: 10
signed_curve25519: 20
required:
- one_time_key_counts
properties:
one_time_key_counts:
type: object
additionalProperties:
type: integer
description: |-
For each key algorithm, the number of unclaimed one-time keys
of that type currently held on the server for this device.
If an algorithm is not listed, the count for that algorithm
is to be assumed zero.
example:
curve25519: 10
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
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
device_keys:
type: object
description: |-
The keys to be downloaded. A map from user ID, to a list of
device IDs, or to an empty list to indicate all devices for the
corresponding user.
additionalProperties:
type: array
items:
type: string
description: "device ID"
example:
"@alice:example.com": []
required:
- device_keys
responses:
200:
description:
The device information
schema:
type: object
properties:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `device_keys` result.
additionalProperties:
type: object
example: {}
device_keys:
type: object
description: |-
Information on the queried devices. A map from user ID, to a
map from device ID to device information. For each device,
the information returned will be the same as uploaded via
`/keys/upload`, with the addition of an `unsigned`
property.
additionalProperties:
requestBody:
content:
application/json:
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
device_keys:
type: object
description: |-
The keys to be downloaded. A map from user ID, to a list of
device IDs, or to an empty list to indicate all devices for the
corresponding user.
additionalProperties:
title: DeviceInformation
allOf:
- $ref: definitions/device_keys.yaml
properties:
unsigned:
title: UnsignedDeviceInfo
type: object
description: |-
Additional data added to the device key information
by intermediate servers, and not covered by the
signatures.
type: array
items:
type: string
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
content:
application/json:
schema:
type: object
properties:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `device_keys` result.
additionalProperties:
type: object
example: {}
device_keys:
type: object
description: |-
Information on the queried devices. A map from user ID, to a
map from device ID to device information. For each device,
the information returned will be the same as uploaded via
`/keys/upload`, with the addition of an `unsigned`
property.
additionalProperties:
type: object
additionalProperties:
title: DeviceInformation
allOf:
- $ref: definitions/device_keys.yaml
properties:
device_display_name:
type: string
description:
The display name which the user set on the device.
example:
"@alice:example.com":
JLAFKJWSCS: {
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"algorithms": [
"m.olm.v1.curve25519-aes-sha2",
"m.megolm.v1.aes-sha2"
],
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"unsigned": {
"device_display_name": "Alice's mobile phone"
}
}
master_keys:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the master cross-signing keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the requesting user
is allowed to see.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example: {
"@alice:example.com": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
}
}
}
self_signing_keys:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the self-signing keys of the queried users. A map
from user ID, to self-signing key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example: {
"@alice:example.com": {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
}
}
}
}
user_signing_keys:
type: object
description: |-
Information on the user-signing key of the user making the
request, if they queried their own device information. A map
from user ID, to user-signing key information. The
information returned will be the same as uploaded via
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example: {
"@alice:example.com": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
}
}
}
}
unsigned:
title: UnsignedDeviceInfo
type: object
description: |-
Additional data added to the device key information
by intermediate servers, and not covered by the
signatures.
properties:
device_display_name:
type: string
description: The display name which the user set on the device.
example:
"@alice:example.com":
JLAFKJWSCS:
user_id: "@alice:example.com"
device_id: JLAFKJWSCS
algorithms:
- m.olm.v1.curve25519-aes-sha2
- m.megolm.v1.aes-sha2
keys:
curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI
ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA
unsigned:
device_display_name: Alice's mobile phone
master_keys:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the master cross-signing keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the requesting user
is allowed to see.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example:
"@alice:example.com":
user_id: "@alice:example.com"
usage:
- master
keys:
ed25519:base64+master+public+key: base64+master+public+key
self_signing_keys:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the self-signing keys of the queried users. A map
from user ID, to self-signing key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example:
"@alice:example.com":
user_id: "@alice:example.com"
usage:
- self_signing
keys:
ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key
signatures:
"@alice:example.com":
ed25519:base64+master+public+key: signature+of+self+signing+key
user_signing_keys:
type: object
description: |-
Information on the user-signing key of the user making the
request, if they queried their own device information. A map
from user ID, to user-signing key information. The
information returned will be the same as uploaded via
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example:
"@alice:example.com":
user_id: "@alice:example.com"
usage:
- user_signing
keys:
ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key
signatures:
"@alice:example.com":
ed25519:base64+master+public+key: signature+of+user+signing+key
tags:
- End-to-end encryption
"/keys/claim":
/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
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
one_time_keys:
type: object
description: |-
The keys to be claimed. A map from user ID, to a map from
device ID to algorithm name.
additionalProperties:
requestBody:
content:
application/json:
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
one_time_keys:
type: object
description: |-
The keys to be claimed. A map from user ID, to a map from
device ID to algorithm name.
additionalProperties:
type: string
description: algorithm
example: "signed_curve25519"
example: {
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
}
required:
- one_time_keys
responses:
200:
description:
The claimed keys.
schema:
type: object
properties:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `one_time_keys` result.
additionalProperties:
type: object
example: {}
one_time_keys:
type: object
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from `<algorithm>:<key_id>` to the key object.
See the [key algorithms](/client-server-api/#key-algorithms) section for information
on the Key Object format.
If necessary, the claimed key might be a fallback key. Fallback
keys are re-used by the server until replaced by the device.
additionalProperties:
type: object
additionalProperties:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will read the link provided in the description
# and figure it out from the other endpoints/example.
# 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']
additionalProperties:
type: string
description: algorithm
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.
content:
application/json:
schema:
type: object
properties:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `one_time_keys` result.
additionalProperties:
type: object
example: {}
one_time_keys:
type: object
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from `<algorithm>:<key_id>` to the key object.
See the [key algorithms](/client-server-api/#key-algorithms) section for information
on the Key Object format.
If necessary, the claimed key might be a fallback key. Fallback
keys are re-used by the server until replaced by the device.
additionalProperties:
type: object
additionalProperties:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will read the link provided in the description
# and figure it out from the other endpoints/example.
# 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
tags:
- End-to-end encryption
"/keys/changes":
/keys/changes:
get:
summary: Query users with recent device key updates.
description: |-
@ -439,48 +390,70 @@ 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
uploaded new device identity keys since this point, nor deleted
existing devices with identity keys since then, will be excluded
from the results.
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
uploaded new device identity keys since this point, nor deleted
existing devices with identity keys since then, will be excluded
from the results.
required: true
x-example: "s72594_4483_1934"
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.
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"
responses:
200:
description:
The list of users who updated their devices.
example: s75689_5632_2435
schema:
type: object
properties:
changed:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who updated their device
identity keys.
example: ["@alice:example.com", "@bob:example.org"]
left:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who may have left all
the end-to-end encrypted rooms they previously shared
with the user.
example: ["@clara:example.com", "@doug:example.org"]
type: string
responses:
"200":
description: The list of users who updated their devices.
content:
application/json:
schema:
type: object
properties:
changed:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who updated their device
identity keys.
example:
- "@alice:example.com"
- "@bob:example.org"
left:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who may have left all
the end-to-end encrypted rooms they previously shared
with the user.
example:
- "@clara:example.com"
- "@doug:example.org"
tags:
- End-to-end encryption
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

102
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,39 +32,44 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being kicked.
reason:
type: string
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"]
properties:
user_id:
type: string
description: The fully qualified user ID of the user being kicked.
reason:
type: string
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: true
responses:
200:
"200":
description: The user has been kicked from the room.
examples:
application/json: {
}
schema:
type: object
403:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
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

146
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,74 +41,107 @@ 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: object
properties:
reason:
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
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"
}
schema:
type: object
properties:
room_id:
type: string
description: The knocked room ID.
required: ["room_id"]
403:
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
description: The knocked room ID.
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."
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: |-
The room could not be found or resolved to a room ID.
examples:
application/json: {
"errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "That room does not appear to exist."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

140
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,39 +36,44 @@ 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: object
example: {
"reason": "Saying farewell - thanks for the support!"
}
properties:
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
responses:
200:
description: |-
The room has been left.
examples:
application/json: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Saying farewell - thanks for the support!"
}
schema:
type: object
429:
properties:
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: true
responses:
"200":
description: The room has been left.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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: {
}
schema:
type: object
400:
"200":
description: The room has been forgotten.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: The user has not left the room
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
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"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

74
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.
schema:
type: object
required: ["joined_rooms"]
properties:
joined_rooms:
type: array
description: |-
The ID of each room in which the user has `joined` membership.
items:
type: string
examples:
application/json: {
"joined_rooms": [
"!foo:example.com"
]
}
content:
application/json:
schema:
type: object
required:
- joined_rooms
properties:
joined_rooms:
type: array
description: The ID of each room in which the user has `joined` membership.
items:
type: string
examples:
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

281
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
schema:
type: object
properties:
visibility:
type: string
enum: ['private', 'public']
description: The visibility of the room in the directory.
examples:
application/json: {
"visibility": "public"
}
404:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum:
- private
- public
description: The visibility of the room in the directory.
examples:
response:
value: {
"visibility": "public"
}
"404":
description: The room is not known to the server
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
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: object
properties:
visibility:
type: string
enum: ["private", "public"]
description: |-
The new visibility setting for the room.
Defaults to 'public'.
example: {
"visibility": "public"
}
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
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: {}
schema:
type: object
404:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: The room is not known to the server
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
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
type: integer
description: |-
Limit the number of results returned.
description: Limit the number of results returned.
schema:
type: integer
- 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,35 +179,32 @@ 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: object
properties:
limit:
type: integer
description: |-
Limit the number of results returned.
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.
filter:
type: object
title: "Filter"
description: |-
Filter to apply to the results.
properties:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: Limit the number of results returned.
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.
filter:
type: object
title: Filter
description: Filter to apply to the results.
properties:
generic_search_term:
type: string
description: |-
@ -210,31 +220,50 @@ paths:
for. To include rooms without a room type, specify `null` within this
list. When not specified, all applicable rooms (regardless of type)
are returned.
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
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.
example: "irc"
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"room_types": [null, "m.space"]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
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.
example: irc
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"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.
schema:
$ref: "definitions/public_rooms_response.yaml"
content:
application/json:
schema:
$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

417
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,45 +26,56 @@ 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}
]
}
schema:
type: object
properties:
flows:
type: array
description: The homeserver's supported login types
items:
type: object
title: LoginFlow
required: ['type']
properties:
type:
description: |-
The login type. This is supplied as the `type` when
logging in.
type: string
get_login_token:
type: boolean
x-addedInMatrixVersion: "1.7"
description: |-
If `type` is `m.login.token`, an optional field to indicate
to the unauthenticated client that the homeserver supports
the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
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:
content:
application/json:
schema:
type: object
properties:
flows:
type: array
description: The homeserver's supported login types
items:
type: object
title: LoginFlow
required:
- type
properties:
type:
description: |-
The login type. This is supplied as the `type` when
logging in.
type: string
get_login_token:
type: boolean
x-addedInMatrixVersion: "1.7"
description: |-
If `type` is `m.login.token`, an optional field to indicate
to the unauthenticated client that the homeserver supports
the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
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.
examples:
response:
value: {
"flows": [
{
"type": "m.login.password"
},
{
"type": "m.login.token",
"get_login_token": true
}
]
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Session management
post:
@ -92,13 +92,12 @@ 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
schema:
type: object
example: {
requestBody:
content:
application/json:
schema:
type: object
example: {
"type": "m.login.password",
"identifier": {
"type": "m.id.user",
@ -107,148 +106,182 @@ paths:
"password": "ilovebananas",
"initial_device_display_name": "Jungle Phone"
}
properties:
type:
type: string
enum: ["m.login.password", "m.login.token"]
description: The login type being used.
identifier:
"$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`.
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`.
address:
type: string
description: Third-party identifier for the user. Deprecated in favour of `identifier`.
password:
type: string
description: |-
Required when `type` is `m.login.password`. The user's
password.
token:
type: string
description: |-
Required when `type` is `m.login.token`. Part of Token-based login.
device_id:
type: string
description: |-
ID of the client device. If this does not correspond to a
known client device, a new device will be created. The given
device ID must not be the same as a
[cross-signing](/client-server-api/#cross-signing) key ID.
The server will auto-generate a device_id
if this is not specified.
initial_device_display_name:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if `device_id` corresponds to a known device.
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
required: ["type"]
properties:
type:
type: string
enum:
- m.login.password
- m.login.token
description: The login type being used.
identifier:
$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`.
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`.
address:
type: string
description: Third-party identifier for the user. Deprecated in favour of
`identifier`.
password:
type: string
description: |-
Required when `type` is `m.login.password`. The user's
password.
token:
type: string
description: Required when `type` is `m.login.token`. Part of Token-based login.
device_id:
type: string
description: |-
ID of the client device. If this does not correspond to a
known client device, a new device will be created. The given
device ID must not be the same as a
[cross-signing](/client-server-api/#cross-signing) key ID.
The server will auto-generate a device_id
if this is not specified.
initial_device_display_name:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if `device_id` corresponds to a known device.
refresh_token:
type: boolean
description: If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
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"
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The fully-qualified Matrix ID for the account.
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
refresh_token:
type: string
description: |-
A refresh token for the account. This token can be used to
obtain a new access token when it expires by calling the
`/refresh` endpoint.
x-addedInMatrixVersion: "1.3"
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. Once
the access token has expired a new access token can be
obtained by using the provided refresh token. If no
refresh token is provided, the client will need to re-log in
to obtain a new access token. If not given, the client can
assume that the access token will not expire.
x-addedInMatrixVersion: "1.3"
home_server:
type: string
description: |-
The server_name of the homeserver on which the account has
been registered.
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The fully-qualified Matrix ID for the account.
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
refresh_token:
type: string
description: |-
A refresh token for the account. This token can be used to
obtain a new access token when it expires by calling the
`/refresh` endpoint.
x-addedInMatrixVersion: "1.3"
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. Once
the access token has expired a new access token can be
obtained by using the provided refresh token. If no
refresh token is provided, the client will need to re-log in
to obtain a new access token. If not given, the client can
assume that the access token will not expire.
x-addedInMatrixVersion: "1.3"
home_server:
type: string
description: |-
The server_name of the homeserver on which the account has
been registered.
**Deprecated**. Clients should extract the server_name from
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
ID of the logged-in device. Will be the same as the
corresponding parameter in the request, if one was specified.
well_known:
description: |-
Optional client configuration provided by the server. If present,
clients SHOULD use the provided object to reconfigure themselves,
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.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
**Deprecated**. Clients should extract the server_name from
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
ID of the logged-in device. Will be the same as the
corresponding parameter in the request, if one was specified.
well_known:
description: |-
Optional client configuration provided by the server. If present,
clients SHOULD use the provided object to reconfigure themselves,
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
examples:
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."
}
"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.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

132
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,55 +54,81 @@ paths:
x-addedInMatrixVersion: "1.7"
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- $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
}
schema:
type: object
required: ["login_token", "expires_in_ms"]
properties:
login_token:
type: string
description: The login token for the `m.login.token` login flow.
expires_in_ms:
type: integer
description: |-
The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
(2 minutes) is recommended as a default.
400:
"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
properties:
login_token:
type: string
description: The login token for the `m.login.token` login flow.
expires_in_ms:
type: integer
description: |-
The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
(2 minutes) is recommended as a default.
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).
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

56
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.
schema:
type: object
properties: {}
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.
schema:
type: object
properties: {}
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

224
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"
example: "!636q39766251:example.com"
schema:
type: string
- in: query
type: string
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"
example: s345_678_333
schema:
type: string
- in: query
type: string
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
schema:
type: string
- in: query
type: string
enum: ["b", "f"]
name: dir
description: |-
The direction to return events from. If this is set to `f`, events
@ -85,92 +75,114 @@ 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
type: string
name: filter
description: |-
A JSON RoomEventFilter to filter returned events with.
x-example: |-
{"contains_url":true}
responses:
200:
description: A list of messages with a new token to request more.
example: b
schema:
type: object
description: A list of messages with a new token to request more.
properties:
start:
type: string
description: |-
A token corresponding to the start of `chunk`. This will be the same as
the value given in `from`.
end:
type: string
description: |-
A token corresponding to the end of `chunk`. This token can be passed
back to this endpoint to request further events.
If no further events are available (either because we have
reached the start of the timeline, or because the user does
not have permission to see any more events), this property
is omitted from the response.
chunk:
type: array
description: |-
A list of room events. The order depends on the `dir` parameter.
For `dir=b` events will be in reverse-chronological order,
for `dir=f` in chronological order. (The exact definition of `chronological`
is dependent on the server implementation.)
Note that an empty `chunk` does not *necessarily* imply that no more events
are available. Clients should continue to paginate until no `end` property
is returned.
items:
"$ref": "definitions/client_event.yaml"
state:
type: array
description: |-
A list of state events relevant to showing the `chunk`. For example, if
`lazy_load_members` is enabled in the filter then this may contain
the membership events for the senders of events in the `chunk`.
Unless `include_redundant_members` is `true`, the server
may remove membership events which would have already been
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]
examples:
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.
example: '{"contains_url":true}'
schema:
type: string
responses:
"200":
description: A list of messages with a new token to request more.
content:
application/json:
{
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk":
[
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.name.yaml",
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml",
},
],
}
403:
description: >
schema:
type: object
description: A list of messages with a new token to request more.
properties:
start:
type: string
description: |-
A token corresponding to the start of `chunk`. This will be the same as
the value given in `from`.
end:
type: string
description: |-
A token corresponding to the end of `chunk`. This token can be passed
back to this endpoint to request further events.
If no further events are available (either because we have
reached the start of the timeline, or because the user does
not have permission to see any more events), this property
is omitted from the response.
chunk:
type: array
description: |-
A list of room events. The order depends on the `dir` parameter.
For `dir=b` events will be in reverse-chronological order,
for `dir=f` in chronological order. (The exact definition of `chronological`
is dependent on the server implementation.)
Note that an empty `chunk` does not *necessarily* imply that no more events
are available. Clients should continue to paginate until no `end` property
is returned.
items:
$ref: definitions/client_event.yaml
state:
type: array
description: |-
A list of state events relevant to showing the `chunk`. For example, if
`lazy_load_members` is enabled in the filter then this may contain
the membership events for the senders of events in the `chunk`.
Unless `include_redundant_members` is `true`, the server
may remove membership events which would have already been
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
examples:
response:
value: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.name.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
]
}
"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

197
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,97 +27,124 @@ 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"
responses:
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"
}
}
]
}
example: highlight
schema:
type: object
required: ["notifications"]
properties:
next_token:
type: string
description: |-
The token to supply in the `from` param of the next
`/notifications` request in order to request more
events. If this is absent, there are no more results.
notifications:
type: array
items:
type: object
required: ["actions", "event", "read", "room_id", "ts"]
title: Notification
properties:
actions:
type: array
description: |-
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
event:
title: Event
description: The Event object for the event that triggered the notification.
allOf:
- "$ref": "definitions/client_event_without_room_id.yaml"
profile_tag:
type: string
description: The profile tag of the rule that matched this event.
read:
type: boolean
description: |-
Indicates whether the user has sent a read receipt indicating
that they have read this message.
room_id:
type: string
description: The ID of the room in which the event was posted.
ts:
type: integer
format: int64
description: |-
The unix timestamp at which the event notification was sent,
in milliseconds.
description: The list of events that triggered notifications.
type: string
responses:
"200":
description: A batch of events is being returned
content:
application/json:
schema:
type: object
required:
- notifications
properties:
next_token:
type: string
description: |-
The token to supply in the `from` param of the next
`/notifications` request in order to request more
events. If this is absent, there are no more results.
notifications:
type: array
items:
type: object
required:
- actions
- event
- read
- room_id
- ts
title: Notification
properties:
actions:
type: array
description: |-
The action(s) to perform when the conditions for this rule are met.
See [Push Rules: API](/client-server-api/#push-rules-api).
items:
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
profile_tag:
type: string
description: The profile tag of the rule that matched this event.
read:
type: boolean
description: |-
Indicates whether the user has sent a read receipt indicating
that they have read this message.
room_id:
type: string
description: The ID of the room in which the event was posted.
ts:
type: integer
format: int64
description: |-
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

493
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,54 +32,61 @@ 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"
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"}
]
}
example: "35000"
schema:
type: object
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the end of `chunk`. This
token should be used in the next request to `/events`.
chunk:
type: array
description: "An array of events."
items:
$ref: "definitions/client_event.yaml"
400:
description: "Bad pagination `from` parameter."
type: integer
responses:
"200":
description: The events received, which may be none.
content:
application/json:
schema:
type: object
properties:
start:
type: string
description: |-
A token which correlates to the start of `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the end of `chunk`. This
token should be used in the next request to `/events`.
chunk:
type: array
description: An array of events.
items:
$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,176 +116,201 @@ 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"
responses:
200:
description: The user's current state.
examples:
application/json: {
"end": "s3456_9_0",
"presence": [
{"$ref": "../../event-schemas/examples/m.presence.yaml"}
],
"account_data": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
],
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
}
]
}
example: "true"
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: boolean
responses:
"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: PaginationChunk
description: "The pagination chunk for this room."
title: RoomInfo
properties:
start:
room_id:
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.
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:
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 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.
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"
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:
$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:
response:
value: {
"end": "s3456_9_0",
"presence": [
{
"$ref": "../../event-schemas/examples/m.presence.yaml"
}
],
"account_data": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
],
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {
"tags": {
"work": {
"order": 1
}
}
}
},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
}
]
}
"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

81
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: object
example: {}
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.
examples:
application/json: {
"access_token": "SomeT0kenHere",
"token_type": "Bearer",
"matrix_server_name": "example.com",
"expires_in": 3600,
}
schema:
$ref: "definitions/openid_token.yaml"
429:
content:
application/json:
schema:
$ref: definitions/openid_token.yaml
examples:
response:
value: {
"access_token": "SomeT0kenHere",
"token_type": "Bearer",
"matrix_server_name": "example.com",
"expires_in": 3600
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

131
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,62 +37,82 @@ 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"
- in: query
type: string
name: room_id
description: |-
The room ID for which events should be returned.
x-example:
- "!somewhere:over.the.rainbow"
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"
}
]
}
example: "35000"
schema:
type: object
properties:
start:
type: string
description: |-
A token which correlates to the first value in `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the last value in `chunk`. This
token should be used in the next request to `/events`.
chunk:
type: array
description: "An array of events."
items:
type: object
title: Event
allOf:
- "$ref": "definitions/client_event.yaml"
400:
description: "Bad pagination `from` parameter."
type: integer
- in: query
name: room_id
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.
content:
application/json:
schema:
type: object
properties:
start:
type: string
description: |-
A token which correlates to the first value in `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the last value in `chunk`. This
token should be used in the next request to `/events`.
chunk:
type: array
description: An array of events.
items:
type: object
title: Event
allOf:
- $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

190
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,99 +29,136 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"presence": "online",
"status_msg": "I am here."
}
properties:
presence:
type: string
enum: ["online", "offline", "unavailable"]
description: The new presence state.
status_msg:
type: string
description: The status message to attach to this state.
required: ["presence"]
properties:
presence:
type: string
enum:
- online
- offline
- unavailable
description: The new presence state.
status_msg:
type: string
description: The status message to attach to this state.
required:
- presence
description: The updated presence state.
required: true
responses:
200:
"200":
description: The new presence state was set.
examples:
application/json: {
}
schema:
type: object # empty json object
429:
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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"
responses:
200:
description: The presence state for this user.
examples:
application/json: {
"presence": "unavailable",
"last_active_ago": 420845
}
example: "@alice:example.com"
schema:
type: object
properties:
presence:
type: string
enum: ["online", "offline", "unavailable"]
description: This user's presence.
last_active_ago:
type: integer
description: |-
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.
currently_active:
type: boolean
description: "Whether the user is currently active"
required: ["presence"]
404:
type: string
responses:
"200":
description: The presence state for this user.
content:
application/json:
schema:
type: object
properties:
presence:
type: string
enum:
- online
- offline
- unavailable
description: This user's presence.
last_active_ago:
type: integer
description: |-
The length of time in milliseconds since an action was performed
by this user.
status_msg:
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
examples:
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.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: You are not allowed to see this user's presence status.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to see their presence"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$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

286
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,36 +27,42 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"displayname": "Alice Margatroid"
}
properties:
displayname:
type: string
description: The new display name for this user.
properties:
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: {
}
schema:
type: object # empty json object
429:
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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"
responses:
200:
description: The display name for this user.
examples:
application/json: {
"displayname": "Alice Margatroid"
}
example: "@alice:example.com"
schema:
type: object
properties:
displayname:
type: string
description: The user's display name if they have set one, otherwise not present.
404:
type: string
responses:
"200":
description: The display name for this user.
content:
application/json:
schema:
type: object
properties:
displayname:
type: string
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,37 +112,43 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
}
properties:
avatar_url:
type: string
format: uri
description: The new avatar URL for this user.
properties:
avatar_url:
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: {
}
schema:
type: object # empty json object
429:
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- User data
get:
@ -154,26 +160,30 @@ 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"
responses:
200:
description: The avatar URL for this user.
examples:
application/json: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
example: "@alice:example.com"
schema:
type: object
properties:
avatar_url:
type: string
format: uri
description: The user's avatar URL if they have set one, otherwise not present.
404:
type: string
responses:
"200":
description: The avatar URL for this user.
content:
application/json:
schema:
type: object
properties:
avatar_url:
type: string
format: uri
description: The user's avatar URL if they have set one, otherwise not present.
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,47 +198,75 @@ 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"
}
schema:
type: object
properties:
avatar_url:
type: string
format: uri
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:
content:
application/json:
schema:
type: object
properties:
avatar_url:
type: string
format: uri
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.
examples:
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Profile lookup over federation is disabled on this homeserver"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: There is no profile information for this user or this user does not exist.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Profile not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
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
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Profile not found"
}
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

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

@ -12,127 +12,117 @@
# 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"
}
}
]
}
schema:
type: object
properties:
pushers:
type: array
title: Pushers
description: |-
An array containing the current pushers for the user
items:
type: object
title: Pusher
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. See `/set` for
more detail.
Max length, 512 bytes.
kind:
type: string
description: |-
The kind of pusher. `"http"` is a pusher that
sends HTTP pokes.
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
Max length, 64 chars.
app_display_name:
type: string
description: |-
A string that will allow the user to identify what application
owns this pusher.
device_display_name:
type: string
description: |-
A string that will allow the user to identify what device owns
this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
data:
content:
application/json:
schema:
type: object
properties:
pushers:
type: array
title: Pushers
description: An array containing the current pushers for the user
items:
type: object
description: |-
A dictionary of information for the pusher implementation
itself.
title: PusherData
title: Pusher
properties:
url:
type: string
format: uri
description: |-
Required if `kind` is `http`. The URL to use to send
notifications to.
format:
pushkey:
type: string
description: |-
The format to use when sending notifications to the Push
Gateway.
required:
- pushkey
- app_id
- kind
- app_display_name
- device_display_name
- lang
- data
This is a unique identifier for this pusher. See `/set` for
more detail.
Max length, 512 bytes.
kind:
type: string
description: |-
The kind of pusher. `"http"` is a pusher that
sends HTTP pokes.
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
Max length, 64 chars.
app_display_name:
type: string
description: |-
A string that will allow the user to identify what application
owns this pusher.
device_display_name:
type: string
description: |-
A string that will allow the user to identify what device owns
this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
data:
type: object
description: |-
A dictionary of information for the pusher implementation
itself.
title: PusherData
properties:
url:
type: string
format: uri
description: |-
Required if `kind` is `http`. The URL to use to send
notifications to.
format:
type: string
description: |-
The format to use when sending notifications to the Push
Gateway.
required:
- pushkey
- app_id
- kind
- app_display_name
- 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,131 +137,155 @@ paths:
operationId: postPusher
security:
- accessToken: []
parameters:
- in: body
name: pusher
description: The pusher information.
required: true
schema:
type: object
example: {
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
"format": "event_id_only"
},
"append": false
}
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. The value you
should use for this is the routing or destination address
information for the notification, for example, the APNS token
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
requestBody:
content:
application/json:
schema:
type: object
example: {
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
"format": "event_id_only"
},
"append": false
}
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. The value you
should use for this is the routing or destination address
information for the notification, for example, the APNS token
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
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.
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
If the `kind` is `"email"`, this is the email address to
send notifications to.
kind:
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: |-
This is a reverse-DNS style identifier for the application.
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
If the `kind` is `"email"`, this is `"m.email"`.
app_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what application owns this pusher.
device_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what device owns this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
Required if `kind` is not `null`. The preferred language for
receiving notifications (e.g. 'en' or 'en-US').
data:
type: object
description: |-
Required if `kind` is not `null`. A dictionary of information
for the pusher implementation itself. If `kind` is `http`,
this should contain `url` which is the URL to use to send
notifications to.
title: PusherData
properties:
url:
type: string
format: uri
description: |-
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"
format:
type: string
description: |-
The format to send notifications in to Push Gateways if the
`kind` is `http`. The details about what fields the
homeserver should send to the push gateway are defined in the
[Push Gateway Specification](/push-gateway-api/). Currently the only format
available is 'event_id_only'.
append:
type: boolean
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
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']
If the `kind` is `"email"`, this is `"m.email"`.
app_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what application owns this pusher.
device_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what device owns this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
Required if `kind` is not `null`. The preferred language for
receiving notifications (e.g. 'en' or 'en-US').
data:
type: object
description: |-
Required if `kind` is not `null`. A dictionary of information
for the pusher implementation itself. If `kind` is `http`,
this should contain `url` which is the URL to use to send
notifications to.
title: PusherData
properties:
url:
type: string
format: uri
description: |-
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
format:
type: string
description: |-
The format to send notifications in to Push Gateways if the
`kind` is `http`. The details about what fields the
homeserver should send to the push gateway are defined in the
[Push Gateway Specification](/push-gateway-api/). Currently the only format
available is 'event_id_only'.
append:
type: boolean
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
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
description: The pusher information.
required: true
responses:
200:
"200":
description: The pusher was set.
examples:
application/json: {}
schema:
type: object
description: An empty object.
400:
content:
application/json:
schema:
type: object
description: An empty object.
examples:
response:
value: {}
"400":
description: One or more of the pusher values were invalid.
examples:
application/json: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

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

File diff suppressed because it is too large Load diff

119
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: object
properties:
"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"
x-changedInMatrixVersion:
1.4: |
This property is no longer required.
"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":
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"
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
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
x-changedInMatrixVersion:
"1.4": |
This property is no longer required.
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:
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
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.
schema:
type: object
properties: {}
429:
"200":
description: The read marker, and read receipt(s) if provided, have been updated.
content:
application/json:
schema:
type: object
properties: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

132
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"
example: "!wefuh21ffskfuh345:example.com"
schema:
type: string
- in: path
type: string
name: receiptType
description: |-
The type of receipt to send. This can also be `m.fully_read` as an
@ -55,63 +44,92 @@ 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"]
example: m.read
schema:
type: string
enum:
- m.read
- m.read.private
- m.fully_read
- in: path
type: string
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: object
properties:
thread_id:
type: string
x-addedInMatrixVersion: "1.4"
description: |-
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
thread_id:
type: string
x-addedInMatrixVersion: "1.4"
description: |-
The root thread event's ID (or `main`) for which
thread this receipt is intended to be under. If
not specified, the read receipt is *unthreaded*
(default).
example: {
"thread_id": "main"
}
responses:
200:
description: The receipt was sent.
examples:
application/json: {
example: {
"thread_id": "main"
}
schema:
type: object
maxProperties: 0 # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
400:
description: |-
Extra receipt information to attach to `content` if any. The
server will automatically set the `ts` field.
required: true
responses:
"200":
description: The receipt was sent.
content:
application/json:
schema:
type: object
maxProperties: 0 # empty json object
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`.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "thread_id field must be a non-empty string"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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

94
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,50 +36,71 @@ 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"
example: "!637q39766251:example.com"
schema:
type: string
- in: path
type: string
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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Indecent material"
}
properties:
reason:
type: string
description: The reason for the event being redacted.
properties:
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"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
"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.
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

145
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,63 +39,81 @@ paths:
Application Service identity assertion is disabled for this endpoint.
operationId: refresh
parameters:
- in: body
name: body
required: true
schema:
type: object
example: {
requestBody:
content:
application/json:
schema:
type: object
example: {
"refresh_token": "some_token"
}
properties:
refresh_token:
type: string
description: The refresh token
required:
- refresh_token
properties:
refresh_token:
type: string
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"
}
schema:
type: object
properties:
access_token:
type: string
description: |-
The new access token to use.
refresh_token:
type: string
description: |-
The new refresh token to use when the access token needs to
be refreshed again. If not given, the old refresh token can
be re-used.
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. If not
given, the client can assume that the access token will not
expire.
required:
- access_token
401:
description: |-
The provided token was unknown, or has already been used.
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Soft logged out",
"soft_logout": true
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
description: The new access token to use.
refresh_token:
type: string
description: |-
The new refresh token to use when the access token needs to
be refreshed again. If not given, the old refresh token can
be re-used.
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. If not
given, the client can assume that the access token will not
expire.
required:
- access_token
examples:
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
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

840
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,129 +64,134 @@ 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
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
- in: body
name: body
required: true
example: user
schema:
type: object
properties:
auth:
description: |-
type: string
enum:
- guest
- user
default: user
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the `register` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
type: string
description: |-
The basis for the localpart of the desired Matrix ID. If omitted,
the homeserver MUST generate a Matrix ID local part.
example: cheeky_monkey
password:
type: string
description: The desired password for the account.
example: ilovebananas
device_id:
type: string
description: |-
ID of the client device. If this does not correspond to a
known client device, a new device will be created. The server
will auto-generate a device_id if this is not specified.
example: GHTYAJCE
initial_device_display_name:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if `device_id` corresponds to a known device.
example: Jungle Phone
inhibit_login:
type: boolean
description: |-
If true, an `access_token` and `device_id` should not be
returned from this call, therefore preventing an automatic
login. Defaults to false.
example: false
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
allOf:
- $ref: definitions/auth_data.yaml
username:
type: string
description: |-
The basis for the localpart of the desired Matrix ID. If omitted,
the homeserver MUST generate a Matrix ID local part.
example: cheeky_monkey
password:
type: string
description: The desired password for the account.
example: ilovebananas
device_id:
type: string
description: |-
ID of the client device. If this does not correspond to a
known client device, a new device will be created. The server
will auto-generate a device_id if this is not specified.
example: GHTYAJCE
initial_device_display_name:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if `device_id` corresponds to a known device.
example: Jungle Phone
inhibit_login:
type: boolean
description: |-
If true, an `access_token` and `device_id` should not be
returned from this call, therefore preventing an automatic
login. Defaults to false.
example: false
refresh_token:
type: boolean
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"
}
schema:
type: object
properties:
user_id:
type: string
description: |-
The fully-qualified Matrix user ID (MXID) that has been registered.
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: |-
The fully-qualified Matrix user ID (MXID) that has been registered.
Any user ID returned by this API must conform to the grammar given in the
[Matrix specification](/appendices/#user-identifiers).
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
Required if the `inhibit_login` option is false.
refresh_token:
type: string
description: |-
A refresh token for the account. This token can be used to
obtain a new access token when it expires by calling the
`/refresh` endpoint.
Any user ID returned by this API must conform to the grammar given in the
[Matrix specification](/appendices/#user-identifiers).
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
Required if the `inhibit_login` option is false.
refresh_token:
type: string
description: |-
A refresh token for the account. This token can be used to
obtain a new access token when it expires by calling the
`/refresh` endpoint.
Omitted if the `inhibit_login` option is true.
x-addedInMatrixVersion: "1.3"
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. Once
the access token has expired a new access token can be
obtained by using the provided refresh token. If no
refresh token is provided, the client will need to re-log in
to obtain a new access token. If not given, the client can
assume that the access token will not expire.
Omitted if the `inhibit_login` option is true.
x-addedInMatrixVersion: "1.3"
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. Once
the access token has expired a new access token can be
obtained by using the provided refresh token. If no
refresh token is provided, the client will need to re-log in
to obtain a new access token. If not given, the client can
assume that the access token will not expire.
Omitted if the `inhibit_login` option is true.
x-addedInMatrixVersion: "1.3"
home_server:
type: string
description: |-
The server_name of the homeserver on which the account has
been registered.
Omitted if the `inhibit_login` option is true.
x-addedInMatrixVersion: "1.3"
home_server:
type: string
description: |-
The server_name of the homeserver on which the account has
been registered.
**Deprecated**. Clients should extract the server_name from
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
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:
**Deprecated**. Clients should extract the server_name from
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
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
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.
examples:
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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/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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$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.
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:
content:
application/json:
schema:
$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.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
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
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$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.
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:
content:
application/json:
schema:
$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.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
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,53 +389,61 @@ paths:
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
new_password:
type: string
description: The new password for the account.
example: "ihatebananas"
logout_devices:
type: boolean
description: |-
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
requestBody:
content:
application/json:
schema:
type: object
properties:
new_password:
type: string
description: The new password for the account.
example: ihatebananas
logout_devices:
type: boolean
description: |-
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
required: ["new_password"]
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
for the user's remaining devices.
example: true
auth:
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- $ref: definitions/auth_data.yaml
required:
- new_password
required: true
responses:
200:
"200":
description: The password has been changed.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
required: true
responses:
200:
"200":
description: An email was sent to the given address.
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:
content:
application/json:
schema:
$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.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Email not found"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
200:
"200":
description: An SMS message was sent to the given phone number.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
content:
application/json:
schema:
$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.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Phone number not found"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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,63 +593,68 @@ paths:
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the `id_server`
that was originally use to bind each identifier. If the
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: "example.org"
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: Additional authentication information for the user-interactive
authentication API.
allOf:
- $ref: definitions/auth_data.yaml
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the `id_server`
that was originally use to bind each identifier. If the
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: example.org
required: true
responses:
200:
"200":
description: The account has been deactivated.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "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
that all identifiers have been unbound from the identity server while
`no-support` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
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"
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- 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
that all identifiers have been unbound from the identity server while
`no-support` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
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
required:
- id_server_unbind_result
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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,27 +674,31 @@ 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.
responses:
200:
description: The username is available
examples:
application/json: {
"available": true
}
example: my_cool_localpart
schema:
type: object
properties:
available:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be `true` when the server replies with 200 OK.
400:
type: string
default: my_cool_localpart
responses:
"200":
description: The username is available
content:
application/json:
schema:
type: object
properties:
available:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be `true` when the server replies with 200 OK.
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.
examples:
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

97
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,41 +31,63 @@ paths:
parameters:
- in: query
name: token
type: string
x-example: "fBVFdqVE"
required: true
description: The token to check validity of.
responses:
200:
description: The check has a result.
examples:
application/json: {
"valid": true
}
example: fBVFdqVE
schema:
type: object
properties:
valid:
type: boolean
description: |-
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:
type: string
responses:
"200":
description: The check has a result.
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: |-
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
examples:
response:
value: {
"valid": true
}
"403":
description: |-
The homeserver does not permit registration and thus all tokens are
considered invalid.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is not enabled on this homeserver."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Registration is not enabled on this homeserver."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

463
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"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
type: string
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: query
type: string
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"
example: page2_token
schema:
type: string
- in: query
type: string
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,63 +91,76 @@ 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"
content:
application/json:
schema:
type: object
properties:
chunk:
title: ChildEventsChunk
type: array
description: The child events of the requested event, ordered topologically
most-recent first.
items:
allOf:
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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
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"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
type: array
description: |-
The child events of the requested event, ordered topologically most-recent first.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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:
"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).
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
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"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
type: string
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"
example: org.example.my_relation
schema:
type: string
- in: query
type: string
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"
example: page2_token
schema:
type: string
- in: query
type: string
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,71 +248,85 @@ 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"
content:
application/json:
schema:
type: object
properties:
chunk:
title: ChildEventsChunk
type: array
description: |-
The child events of the requested event, ordered topologically
most-recent first. The events returned will match the `relType`
supplied in the URL.
items:
allOf:
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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
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"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
type: array
description: |-
The child events of the requested event, ordered topologically
most-recent first. The events returned will match the `relType`
supplied in the URL.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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:
"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).
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
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"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
type: string
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"
example: org.example.my_relation
schema:
type: string
- in: path
type: string
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"
example: m.room.message
schema:
type: string
- in: query
type: string
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"
example: page2_token
schema:
type: string
- in: query
type: string
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,65 +419,92 @@ 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"
content:
application/json:
schema:
type: object
properties:
chunk:
title: ChildEventsChunk
type: array
description: |-
The child events of the requested event, ordered topologically most-recent
first. The events returned will match the `relType` and `eventType` supplied
in the URL.
items:
allOf:
- $ref: definitions/client_event.yaml
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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
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"
}
}
}],
"next_batch": "page2_token",
"prev_batch": "page1_token"
}
schema:
type: object
properties:
chunk:
title: "ChildEventsChunk"
type: array
description: |-
The child events of the requested event, ordered topologically most-recent
first. The events returned will match the `relType` and `eventType` supplied
in the URL.
items:
allOf:
- "$ref": "definitions/client_event.yaml"
next_batch:
type: string
description: |-
An opaque string representing a pagination token. The absence of this token
means there are no more results to fetch and the client should stop paginating.
prev_batch:
type: string
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:
"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).
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
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

90
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,43 +25,64 @@ 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"
example: "!637q39766251:example.com"
schema:
type: string
- in: path
type: string
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: object
example: {
"score": -100,
"reason": "this makes me sad"
}
properties:
score:
type: integer
description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
reason:
type: string
description: The reason the content is being reported. May be blank.
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"score": -100,
"reason": "this makes me sad"
}
properties:
score:
type: integer
description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
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.
schema:
type: object
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
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

134
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,64 +49,91 @@ 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.
schema:
type: object
properties:
event_id:
type: string
description: |-
The ID of the event found
origin_server_ts:
type: integer
description: |-
The event's timestamp, in milliseconds since the Unix epoch.
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']
examples:
application/json: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
404:
description: |-
No event was found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"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
origin_server_ts:
type: integer
description: |-
The event's timestamp, in milliseconds since the Unix epoch.
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
examples:
response:
value: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
"404":
description: No event was found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
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/v1
components:
securitySchemes:
$ref: definitions/security.yaml

271
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,127 +18,161 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get the data.
required: true
x-example: "!636q39766251:example.com"
responses:
200:
description: The current state of the room
examples:
application/json: {
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!636q39766251:example.com",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [{
"type": "m.tag",
"content": {"tags": {"work": {"order": "1"}}}
}]
}
example: "!636q39766251:example.com"
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: string
responses:
"200":
description: The current state of the room
content:
application/json:
schema:
title: RoomInfo
type: object
title: PaginationChunk
description: "The pagination chunk for this room."
properties:
start:
room_id:
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.
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:
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 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.
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"
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.
$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:
response:
value: {
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!636q39766251:example.com",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {
"tags": {
"work": {
"order": "1"
}
}
}
}
]
}
"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

98
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"
example: "!636q39766251:example.com"
schema:
type: string
- in: path
type: string
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: object
example: {
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"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
400:
"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.
required:
- event_id
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).
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$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

131
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,62 +42,58 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.member"
example: m.room.member
schema:
type: string
- in: path
type: string
name: stateKey
description: |-
The state_key for the state to send. Defaults to the empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: "@alice:example.com"
- in: body
name: body
required: true
example: "@alice:example.com"
schema:
type: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"membership": "join",
"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"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
400:
"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.
required:
- event_id
examples:
response:
value: {
"event_id": "$YUwRidLecu:example.com"
}
"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.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_BAD_ALIAS",
"error": "The alias '#hello:example.org' does not point to this room."
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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

133
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: object
properties:
new_version:
type: string
description: The new version for the room.
example: {"new_version": "2"}
required: [new_version]
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
required: true
responses:
200:
"200":
description: The room was successfully upgraded.
examples:
application/json: {
"replacement_room": "!newroom:example.org"
}
schema:
type: object
properties:
replacement_room:
type: string
description: The ID of the new room.
required: [replacement_room]
400:
content:
application/json:
schema:
type: object
properties:
replacement_room:
type: string
description: The ID of the new room.
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.
examples:
application/json: {
"errcode": "M_UNSUPPORTED_ROOM_VERSION",
"error": "This server does not support that room version"
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The user is not permitted to upgrade the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You cannot upgrade this room"
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
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
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You cannot upgrade this room"
}
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

371
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"
example: "!636q39766251:matrix.org"
schema:
type: string
- in: path
type: string
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.
examples:
application/json: {
"room_id": "!636q39766251:matrix.org",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
schema:
"$ref": "definitions/client_event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/client_event.yaml
examples:
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/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}/{stateKey}":
@ -83,225 +81,260 @@ 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"
example: "!636q39766251:example.com"
schema:
type: string
- in: path
type: string
name: eventType
description: The type of state to look up.
required: true
x-example: "m.room.name"
example: m.room.name
schema:
type: string
- in: path
type: string
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: ""
responses:
200:
description: The content of the state event.
examples:
application/json: {
"name": "Example room name"}
example: ""
schema:
type: object
404:
type: string
responses:
"200":
description: The content of the state event.
content:
application/json:
schema:
type: object
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"
responses:
200:
description: The current state of the room
examples:
application/json: [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
]
example: "!636q39766251:example.com"
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.
type: string
responses:
"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:
response:
value: [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
]
"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"
example: join
schema:
type: string
enum:
- join
- invite
- knock
- leave
- ban
- in: query
name: not_membership
type: string
enum:
- join
- invite
- knock
- leave
- ban
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.
examples:
application/json: {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
content:
application/json:
schema:
type: object
properties:
chunk:
type: array
items:
$ref: definitions/client_event.yaml
examples:
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
}
]
}
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"
}
}
}
schema:
type: object
properties:
joined:
additionalProperties:
title: RoomMember
type: object
properties:
display_name:
type: string
description: The display name of the user this object is representing.
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: A map from user ID to a RoomMember object.
"200":
description: A map of MXID to room member objects.
content:
application/json:
schema:
type: object
403:
description: >
properties:
joined:
additionalProperties:
title: RoomMember
type: object
properties:
display_name:
type: string
description: The display name of the user this object is representing.
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: A map from user ID to a RoomMember object.
type: object
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

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

@ -11,44 +11,33 @@
# 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"search_categories": {
"room_events": {
"keys": [
@ -66,300 +55,323 @@ paths:
}
}
}
properties:
search_categories:
type: object
title: "Categories"
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
type: string
description: The string to search events for
keys:
type: array
items:
properties:
search_categories:
type: object
title: Categories
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
type: string
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).
allOf:
- $ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string
enum: ["recent", "rank"]
description: |-
The order in which to search for results.
By default, this is `"rank"`.
event_context:
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
returned are included in the response.
properties:
description: The string to search events for
keys:
type: array
items:
type: string
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).
allOf:
- $ref: definitions/room_event_filter.yaml
order_by:
title: Ordering
type: string
enum:
- recent
- rank
description: |-
The order in which to search for results.
By default, this is `"rank"`.
event_context:
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
returned are included in the response.
properties:
before_limit:
type: integer
title: "Before limit"
description: |-
How many events before the result are
returned. By default, this is `5`.
type: integer
title: Before limit
description: |-
How many events before the result are
returned. By default, this is `5`.
after_limit:
type: integer
title: "After limit"
description: |-
How many events after the result are
returned. By default, this is `5`.
type: integer
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"
description: |-
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is `false`.
include_state:
type: boolean
title: Include current state
description: |-
Requests the server return the current state for
each room returned.
groupings:
type: boolean
title: Return profile information
description: |-
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is `false`.
include_state:
type: boolean
title: Include current state
description: |-
Requests the server return the current state for
each room returned.
groupings:
type: object
title: Groupings
description: |-
Requests that the server partitions the result set
based on the provided list of keys.
properties:
group_by:
type: array
title: Groups
description: List of groups to request.
items:
type: object
title: Group
description: Configuration for group.
properties:
key:
type: string
title: Group Key
description: Key that defines the group.
enum:
- room_id
- sender
required:
- search_term
required:
- search_categories
required: true
responses:
"200":
description: Results of the search.
content:
application/json:
schema:
type: object
title: Results
required:
- search_categories
properties:
search_categories:
type: object
title: Result Categories
description: Describes which categories to search in and their criteria.
properties:
room_events:
type: object
title: Groupings
description: |-
Requests that the server partitions the result set
based on the provided list of keys.
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
group_by:
count:
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array
title: Groups
description: List of groups to request.
title: Highlights
description: List of words which should be highlighted, useful for stemming
which may change the query terms.
items:
type: string
results:
type: array
title: Results
description: List of results in the requested order.
items:
type: object
title: Group
description: Configuration for group.
title: Result
description: The result object.
properties:
key:
type: string
title: Group Key
description: |-
Key that defines the group.
enum: ["room_id", "sender"]
required: ["search_term"]
required: ["search_categories"]
responses:
200:
description: Results of the search.
schema:
type: object
title: Results
required: ["search_categories"]
properties:
search_categories:
type: object
title: Result Categories
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming which may change the query terms.
items:
type: string
results:
type: array
title: Results
description: List of results in the requested order.
items:
type: object
title: Result
description: The result object.
properties:
rank:
type: number
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"
context:
type: object
title: Event Context
description: Context for result, if requested.
properties:
start:
type: string
title: Start Token
description: |-
Pagination token for the start of the chunk
end:
type: string
title: End Token
description: |-
Pagination token for the end of the chunk
profile_info:
rank:
type: number
description: A number that describes how closely this result matches the search.
Higher is closer.
result:
type: object
title: Profile Information
description: |-
The historic profile information of the
users that sent the events returned.
title: Event
description: The event that matched.
allOf:
- $ref: definitions/client_event.yaml
context:
type: object
title: Event Context
description: Context for result, if requested.
properties:
start:
type: string
title: Start Token
description: Pagination token for the start of the chunk
end:
type: string
title: End Token
description: Pagination token for the end of the chunk
profile_info:
type: object
title: Profile Information
description: |-
The historic profile information of the
users that sent the events returned.
The `string` key is the user ID for which
the profile belongs to.
additionalProperties:
type: object
title: User Profile
properties:
displayname:
type: string
title: Display name
avatar_url:
type: string
format: uri
title: Avatar Url
events_before:
type: array
title: Events Before
description: Events just before the result.
items:
title: Event
type: object
"$ref": "definitions/client_event.yaml"
events_after:
type: array
title: Events After
description: Events just after the result.
items:
title: Event
type: object
"$ref": "definitions/client_event.yaml"
state:
type: object
title: Current state
description: |-
The current state for every room in the results.
This is included if the request had the
`include_state` key set with a value of `true`.
The `string` key is the room ID for which the `State
Event` array belongs to.
additionalProperties:
type: array
title: Room State
items:
"$ref": "definitions/client_event.yaml"
groups:
type: object
title: Groups
description: |-
Any groups that were requested.
The outer `string` key is the group key requested (eg: `room_id`
or `sender`). The inner `string` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
description: The results for a given group.
additionalProperties:
The `string` key is the user ID for which
the profile belongs to.
additionalProperties:
type: object
title: User Profile
properties:
displayname:
type: string
title: Display name
avatar_url:
type: string
format: uri
title: Avatar Url
events_before:
type: array
title: Events Before
description: Events just before the result.
items:
title: Event
type: object
$ref: definitions/client_event.yaml
events_after:
type: array
title: Events After
description: Events just after the result.
items:
title: Event
type: object
$ref: definitions/client_event.yaml
state:
type: object
title: Group Value
title: Current state
description: |-
The results for a particular group value.
properties:
next_batch:
type: string
title: Next Batch in Group
description: |-
Token that can be used to get the next batch
of results in the group, by passing as the
`next_batch` parameter to the next call. If
this field is absent, there are no more
results in this group.
order:
type: integer
title: Group Order
description: |-
Key that can be used to order different
groups.
results:
type: array
description: |-
Which results are in this group.
items:
type: string
title: Result Event ID
next_batch:
type: string
title: Next Batch
description: |-
Token that can be used to get the next batch of
results, by passing as the `next_batch` parameter to
the next call. If this field is absent, there are no
more results.
examples:
application/json: {
"search_categories": {
"room_events": {
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"order": 1,
"next_batch": "BdgFsdfHSf-dsFD",
"results": [
"$144429830826TWwbB:localhost"
]
The current state for every room in the results.
This is included if the request had the
`include_state` key set with a value of `true`.
The `string` key is the room ID for which the `State
Event` array belongs to.
additionalProperties:
type: array
title: Room State
items:
$ref: definitions/client_event.yaml
groups:
type: object
title: Groups
description: |-
Any groups that were requested.
The outer `string` key is the group key requested (eg: `room_id`
or `sender`). The inner `string` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
description: The results for a given group.
additionalProperties:
type: object
title: Group Value
description: The results for a particular group value.
properties:
next_batch:
type: string
title: Next Batch in Group
description: |-
Token that can be used to get the next batch
of results in the group, by passing as the
`next_batch` parameter to the next call. If
this field is absent, there are no more
results in this group.
order:
type: integer
title: Group Order
description: |-
Key that can be used to order different
groups.
results:
type: array
description: Which results are in this group.
items:
type: string
title: Result Event ID
next_batch:
type: string
title: Next Batch
description: |-
Token that can be used to get the next batch of
results, by passing as the `next_batch` parameter to
the next call. If this field is absent, there are no
more results.
examples:
response:
value: {
"search_categories": {
"room_events": {
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"order": 1,
"next_batch": "BdgFsdfHSf-dsFD",
"results": [
"$144429830826TWwbB:localhost"
]
}
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [
{
"rank": 0.00424866,
"result": {
"room_id": "!qPewotXpIctQySfjSy:localhost",
"event_id": "$144429830826TWwbB:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [
{
"rank": 0.00424866,
"result": {
"room_id": "!qPewotXpIctQySfjSy:localhost",
"event_id": "$144429830826TWwbB:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
}
}
]
]
}
}
}
}
400:
"400":
description: Part of the request was invalid.
429:
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

269
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
example: 20
schema:
type: integer
- in: query
type: integer
name: max_depth
description: |-
Optional limit for how far to go into the space. Must be a non-negative integer.
@ -75,91 +66,117 @@ 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"
responses:
200:
description: |-
A portion of the space tree, starting at the provided room ID.
examples:
application/json: {
"rooms": [
{
"room_id": "!space:example.org",
"avatar_url": "mxc://example.org/abcdef",
"guest_can_join": false,
"name": "The First Space",
"topic": "No other spaces were created first, ever",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space",
"num_joined_members": 42,
"canonical_alias": "#general:example.org",
"children_state": [
{
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": ["example.org"]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
}
]
}
],
"next_batch": "next_batch_token"
}
example: next_batch_token
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:
# 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.
type: string
responses:
"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: |-
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]
403:
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:
response:
value: {
"rooms": [
{
"room_id": "!space:example.org",
"avatar_url": "mxc://example.org/abcdef",
"guest_can_join": false,
"name": "The First Space",
"topic": "No other spaces were created first, ever",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space",
"num_joined_members": 42,
"canonical_alias": "#general:example.org",
"children_state": [
{
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": [
"example.org"
]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
}
]
}
],
"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.
- `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.
examples:
application/json: {
"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:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to view this room."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

50
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,20 +30,22 @@ 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
- Session management
"/login/sso/redirect/{idpId}":
get:
x-addedInMatrixVersion: "1.1"
@ -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.
schema:
type: string
- 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"
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
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

817
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,405 +112,436 @@ paths:
By default, this is `0`, so the server will return immediately
even if the response is empty.
x-example: 30000
responses:
200:
description:
The initial snapshot or delta for the client to use to update their
state.
example: 30000
schema:
type: object
properties:
next_batch:
type: string
description: |-
The batch token to supply in the `since` param of the next
`/sync` request.
rooms:
title: Rooms
type: integer
responses:
"200":
description: The initial snapshot or delta for the client to use to update their
state.
content:
application/json:
schema:
type: object
description: |-
Updates to rooms.
properties:
join:
title: Joined Rooms
type: object
next_batch:
type: string
description: |-
The rooms that the user has joined, mapped as room ID to
room information.
additionalProperties:
title: Joined Room
type: object
properties:
summary:
title: RoomSummary
The batch token to supply in the `since` param of the next
`/sync` request.
rooms:
title: Rooms
type: object
description: Updates to rooms.
properties:
join:
title: Joined Rooms
type: object
description: |-
The rooms that the user has joined, mapped as room ID to
room information.
additionalProperties:
title: Joined Room
type: object
description: |-
Information about the room which clients may need to
correctly render it to users.
properties:
"m.heroes":
type: array
summary:
title: RoomSummary
type: object
description: |-
The users which can be used to generate a room name
if the room does not have one. Required if the room's
`m.room.name` or `m.room.canonical_alias` state events
are unset or empty.
Information about the room which clients may need to
correctly render it to users.
properties:
m.heroes:
type: array
description: |-
The users which can be used to generate a room name
if the room does not have one. Required if the room's
`m.room.name` or `m.room.canonical_alias` state events
are unset or empty.
This should be the first 5 members of the room, ordered
by stream ordering, which are joined or invited. The
list must never include the client's own user ID. When
no joined or invited members are available, this should
consist of the banned and left users. More than 5 members
may be provided, however less than 5 should only be provided
when there are less than 5 members to represent.
This should be the first 5 members of the room, ordered
by stream ordering, which are joined or invited. The
list must never include the client's own user ID. When
no joined or invited members are available, this should
consist of the banned and left users. More than 5 members
may be provided, however less than 5 should only be provided
when there are less than 5 members to represent.
When lazy-loading room members is enabled, the membership
events for the heroes MUST be included in the `state`,
unless they are redundant. When the list of users changes,
the server notifies the client by sending a fresh list of
heroes. If there are no changes since the last sync, this
field may be omitted.
items:
type: string
"m.joined_member_count":
type: integer
When lazy-loading room members is enabled, the membership
events for the heroes MUST be included in the `state`,
unless they are redundant. When the list of users changes,
the server notifies the client by sending a fresh list of
heroes. If there are no changes since the last sync, this
field may be omitted.
items:
type: string
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:
type: integer
description: |-
The number of users with `membership` of `invite`.
If this field has not changed since the last sync, it
may be omitted. Required otherwise.
state:
title: State
type: object
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":
type: integer
Updates to the state, between the time indicated by
the `since` parameter, and the start of the
`timeline` (or all state up to the start of the
`timeline`, if `since` is not given, or
`full_state` is true).
N.B. state updates for `m.room.member` events will
be incomplete if `lazy_load_members` is enabled in
the `/sync` filter, and only return the member events
required to display the senders of the timeline events
in this response.
allOf:
- $ref: definitions/state_event_batch.yaml
timeline:
title: Timeline
type: object
description: |-
The number of users with `membership` of `invite`.
If this field has not changed since the last sync, it
may be omitted. Required otherwise.
state:
title: State
type: object
description: |-
Updates to the state, between the time indicated by
the `since` parameter, and the start of the
`timeline` (or all state up to the start of the
`timeline`, if `since` is not given, or
`full_state` is true).
The timeline of messages and state changes in the
room.
allOf:
- $ref: definitions/timeline_batch.yaml
ephemeral:
title: Ephemeral
type: object
description: |-
The new ephemeral events in the room (events that
aren't recorded in the timeline or state of the
room). In this version of the spec, these are
[typing notification](#typing-notifications) and
[read receipt](#receipts) events.
allOf:
- $ref: definitions/event_batch.yaml
account_data:
title: Account Data
type: object
description: |-
The private data that this user has attached to
this room.
allOf:
- $ref: definitions/event_batch.yaml
unread_notifications:
title: Unread Notification Counts
type: object
description: |-
Counts of unread notifications for this room. See the
[Receiving notifications](/client-server-api/#receiving-notifications) section
for more information on how these are calculated.
N.B. state updates for `m.room.member` events will
be incomplete if `lazy_load_members` is enabled in
the `/sync` filter, and only return the member events
required to display the senders of the timeline events
in this response.
allOf:
- $ref: "definitions/state_event_batch.yaml"
timeline:
title: Timeline
type: object
description: |-
The timeline of messages and state changes in the
room.
allOf:
- $ref: "definitions/timeline_batch.yaml"
ephemeral:
title: Ephemeral
type: object
description: |-
The new ephemeral events in the room (events that
aren't recorded in the timeline or state of the
room). In this version of the spec, these are
[typing notification](#typing-notifications) and
[read receipt](#receipts) events.
allOf:
- $ref: "definitions/event_batch.yaml"
account_data:
title: Account Data
type: object
description: |-
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
unread_notifications:
title: Unread Notification Counts
type: object
description: |-
Counts of unread notifications for this room. See the
[Receiving notifications](/client-server-api/#receiving-notifications) section
for more information on how these are calculated.
If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
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": |
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.
notification_count:
title: Total notification count
type: integer
description: The total number of unread notifications for this room.
unread_thread_notifications:
title: Unread Thread Notification Counts
type: object
description: |-
If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
the notification counts for each [thread](#threading) in this room. The object is
keyed by thread root ID, with values matching `unread_notifications`.
If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
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: |
Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
the `RoomEventFilter` for `/sync`.
If a thread does not have any notifications it can be omitted from this object. If
no threads have notification counts, this whole object can be omitted.
x-addedInMatrixVersion: "1.4"
additionalProperties:
title: ThreadNotificationCounts
type: object
properties:
highlight_count:
title: ThreadedHighlightNotificationCount
type: integer
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*.
invite:
title: Invited Rooms
type: object
description: |-
The rooms that the user has been invited to, mapped as room ID to
room information.
additionalProperties:
title: Invited Room
type: object
properties:
highlight_count:
title: Highlighted notification count
type: integer
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.
unread_thread_notifications:
title: Unread Thread Notification Counts
invite_state:
title: InviteState
type: object
description: |-
The [stripped state](#stripped-state) of a room that the user has been invited
to.
properties:
events:
description: The [stripped state events](#stripped-state) that form the invite
state.
items:
$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.
additionalProperties:
title: Knocked Room
type: object
description: |-
If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
the notification counts for each [thread](#threading) in this room. The object is
keyed by thread root ID, with values matching `unread_notifications`.
If a thread does not have any notifications it can be omitted from this object. If
no threads have notification counts, this whole object can be omitted.
x-addedInMatrixVersion: "1.4"
additionalProperties:
title: ThreadNotificationCounts
type: object
properties:
highlight_count:
title: ThreadedHighlightNotificationCount
type: integer
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*.
invite:
title: Invited Rooms
properties:
knock_state:
title: KnockState
type: object
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.
items:
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: array
leave:
title: Left rooms
type: object
description: |-
The rooms that the user has left or been banned from, mapped as room ID to
room information.
additionalProperties:
title: Left Room
type: object
properties:
state:
title: State
type: object
description: The state updates for the room up to the start of the timeline.
allOf:
- $ref: definitions/state_event_batch.yaml
timeline:
title: Timeline
type: object
description: |-
The timeline of messages and state changes in the
room up to the point when the user left.
allOf:
- $ref: definitions/timeline_batch.yaml
account_data:
title: Account Data
type: object
description: |-
The private data that this user has attached to
this room.
allOf:
- $ref: definitions/event_batch.yaml
presence:
title: Presence
type: object
description: The updates to the presence status of other users.
allOf:
- $ref: definitions/event_batch.yaml
account_data:
title: Account Data
type: object
description: The global private data created by this user.
allOf:
- $ref: definitions/event_batch.yaml
to_device:
title: ToDevice
type: object
description: |-
The rooms that the user has been invited to, mapped as room ID to
room information.
additionalProperties:
title: Invited Room
type: object
properties:
invite_state:
title: InviteState
type: object
description: |-
The [stripped state](#stripped-state) of a room that the user has been invited
to.
properties:
events:
description: The [stripped state events](#stripped-state) that form the invite state.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
type: array
knock:
title: Knocked rooms
Information on the send-to-device messages for the client
device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync).
device_lists:
title: DeviceLists
type: object
description: |-
The rooms that the user has knocked upon, mapped as room ID to room information.
additionalProperties:
title: Knocked Room
type: object
properties:
knock_state:
title: KnockState
type: object
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.
items:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
type: array
leave:
title: Left rooms
Information on end-to-end device updates, as specified in
[End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
device_one_time_keys_count:
title: One-time keys count
type: object
description: |-
The rooms that the user has left or been banned from, mapped as room ID to
room information.
additionalProperties:
title: Left Room
type: object
properties:
state:
title: State
type: object
description: |-
The state updates for the room up to the start of the timeline.
allOf:
- $ref: "definitions/state_event_batch.yaml"
timeline:
title: Timeline
type: object
description: |-
The timeline of messages and state changes in the
room up to the point when the user left.
allOf:
- $ref: "definitions/timeline_batch.yaml"
account_data:
title: Account Data
type: object
description: |-
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
presence:
title: Presence
type: object
description: |-
The updates to the presence status of other users.
allOf:
- $ref: "definitions/event_batch.yaml"
account_data:
title: Account Data
type: object
description: |-
The global private data created by this user.
allOf:
- $ref: "definitions/event_batch.yaml"
to_device:
title: ToDevice
type: object
description: |-
Information on the send-to-device messages for the client
device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync).
device_lists:
title: DeviceLists
type: object
description: |-
Information on end-to-end device updates, as specified in
[End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
device_one_time_keys_count:
title: One-time keys count
type: object
additionalProperties:
type: integer
description: |-
Information on end-to-end encryption keys, as specified
in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
required:
- next_batch
examples:
application/json: {
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{"$ref": "../../event-schemas/examples/m.presence.yaml"}
]
},
"account_data": {
"events": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
},
"rooms": {
"join": {
"!726s6s6q:example.com": {
"summary": {
"m.heroes": [
"@alice:example.com",
"@bob:example.com"
],
"m.joined_member_count": 2,
"m.invited_member_count": 0
},
"state": {
"events": [
{
"$ref": "../../event-schemas/examples/m.room.member.yaml"
type: integer
description: |-
Information on end-to-end encryption keys, as specified
in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
required:
- next_batch
examples:
response:
value: {
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{
"$ref": "../../event-schemas/examples/m.presence.yaml"
}
]
},
"account_data": {
"events": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
]
},
"timeline": {
"events": [
{
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
},
"rooms": {
"join": {
"!726s6s6q:example.com": {
"summary": {
"m.heroes": [
"@alice:example.com",
"@bob:example.com"
],
"m.joined_member_count": 2,
"m.invited_member_count": 0
},
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
],
"limited": true,
"prev_batch": "t34-23535_0_0"
},
"ephemeral": {
"events": [
{"$ref": "../../event-schemas/examples/m.typing.yaml"},
{"$ref": "../../event-schemas/examples/m.receipt.yaml"}
]
},
"account_data": {
"events": [
{"$ref": "../../event-schemas/examples/m.tag.yaml"},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
"state": {
"events": [
{
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
},
"timeline": {
"events": [
{
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
],
"limited": true,
"prev_batch": "t34-23535_0_0"
},
"ephemeral": {
"events": [
{
"$ref": "../../event-schemas/examples/m.typing.yaml"
},
{
"$ref": "../../event-schemas/examples/m.receipt.yaml"
}
]
},
"account_data": {
"events": [
{
"$ref": "../../event-schemas/examples/m.tag.yaml"
},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
},
"unread_notifications": {
"highlight_count": 1,
"notification_count": 5
},
"unread_thread_notifications": {
"$threadroot": {
"highlight_count": 3,
"notification_count": 6
}
}
]
},
"unread_notifications": {
"highlight_count": 1,
"notification_count": 5
},
"unread_thread_notifications": {
"$threadroot": {
"highlight_count": 3,
"notification_count": 6
}
}
}
},
"invite": {
"!696r7674:example.com": {
"invite_state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {"name": "My Room Name"}
},
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "invite"}
},
"invite": {
"!696r7674:example.com": {
"invite_state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {
"name": "My Room Name"
}
},
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {
"membership": "invite"
}
}
]
}
]
}
}
},
"knock": {
"!223asd456:example.com": {
"knock_state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {"name": "My Room Name"}
},
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "knock"}
}
},
"knock": {
"!223asd456:example.com": {
"knock_state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.name",
"state_key": "",
"content": {
"name": "My Room Name"
}
},
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {
"membership": "knock"
}
}
]
}
]
}
}
},
"leave": {}
}
},
"leave": {}
}
}
}
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

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

@ -12,172 +12,186 @@
# 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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to get tags for.
x-example: "!726s6s6q:example.com"
responses:
200:
description:
The list of tags for the user for the room.
description: The ID of the room to get tags for.
example: "!726s6s6q:example.com"
schema:
type: object
properties:
tags:
type: string
responses:
"200":
description: The list of tags for the user for the room.
content:
application/json:
schema:
type: object
additionalProperties:
title: Tag
type: object
properties:
order:
type: number
format: float
description: |-
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
examples:
application/json: {
"tags": {
"m.favourite": {"order": 0.1},
"u.Work": {"order": 0.7},
"u.Customers": {}
}
}
properties:
tags:
type: object
additionalProperties:
title: Tag
type: object
properties:
order:
type: number
format: float
description: |-
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
examples:
response:
value: {
"tags": {
"m.favourite": {
"order": 0.1
},
"u.Work": {
"order": 0.7
},
"u.Customers": {}
}
}
tags:
- User data
"/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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to add a tag to.
x-example: "!726s6s6q:example.com"
description: The ID of the room to add a tag to.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
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: object
properties:
order:
type: number
format: float
description: |-
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
example: {
"order": 0.25
}
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
order:
type: number
format: float
description: |-
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
example: {
"order": 0.25
}
description: Extra data for the tag, e.g. ordering.
required: true
responses:
200:
description:
The tag was successfully added.
schema:
type: object
examples:
application/json: {}
"200":
description: The tag was successfully added.
content:
application/json:
schema:
type: object
examples:
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"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to remove a tag from.
x-example: "!726s6s6q:example.com"
description: The ID of the room to remove a tag from.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
name: tag
required: true
description: |-
The tag to remove.
x-example: "u.work"
responses:
200:
description:
The tag was successfully removed.
description: The tag to remove.
example: u.work
schema:
type: object
examples:
application/json: {}
type: string
responses:
"200":
description: The tag was successfully removed.
content:
application/json:
schema:
type: object
examples:
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

225
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,41 +27,48 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The protocols supported by the homeserver.
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
tags:
- Third-party Lookup
"/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.
schema:
$ref: ../application-service/definitions/protocol.yaml
404:
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol.yaml
"404":
description: The protocol is unknown.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
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.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
content:
application/json:
schema:
$ref: ../application-service/definitions/location_batch.yaml
"404":
description: No portal rooms were found.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
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...
type: string
description: |-
One or more custom fields that are passed to the AS to help identify the user.
description: One or more custom fields that are passed to the AS to help
identify the user.
schema:
type: string
responses:
200:
"200":
description: The Matrix User IDs found with the given parameters.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
content:
application/json:
schema:
$ref: ../application-service/definitions/user_batch.yaml
"404":
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
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.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: ../application-service/definitions/location_batch.yaml
"404":
description: The Matrix room alias was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
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.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: ../application-service/definitions/user_batch.yaml
"404":
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
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

131
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,56 +60,64 @@ 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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"medium": "email",
"address": "cheeky@monkey.com"
}
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example
`email` (see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example
`email` (see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
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: {
}
schema:
type: object
403:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

174
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,67 +30,97 @@ 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"
example: "!room:example.org"
schema:
type: string
- in: query
type: string
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"
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"
}
example: next_batch_token
schema:
type: object
properties:
chunk:
type: array
description: |-
The thread roots, ordered by the `latest_event` in each event's aggregated children. All events
returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events).
type: string
responses:
"200":
description: A portion of the available thread roots in the room, based on the
filter criteria.
content:
application/json:
schema:
type: object
properties:
chunk:
type: array
description: |-
The thread roots, ordered by the `latest_event` in each event's aggregated children. All events
returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events).
If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the
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"
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:
If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the
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
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
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.
examples:
application/json: {
"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:
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to view this room."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

104
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,54 +27,72 @@ 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: object
title: body
properties:
messages:
type: object
description: |-
The messages to send. A map from user ID, to a map from
device ID to message body. The device ID may also be `*`,
meaning all known devices for the user.
additionalProperties:
type: string
requestBody:
content:
application/json:
schema:
type: object
title: body
properties:
messages:
type: object
description: |-
The messages to send. A map from user ID, to a map from
device ID to message body. The device ID may also be `*`,
meaning all known devices for the user.
additionalProperties:
type: object
title: EventContent
description: Message content
example: {
"@alice:example.com": {
"TLLBEANAAG": {
"example_content_key": "value"
}
}
}
required: ["messages"]
additionalProperties:
type: object
title: EventContent
description: Message content
example:
"@alice:example.com":
TLLBEANAAG:
example_content_key: value
required:
- messages
required: true
responses:
200:
description:
The message was successfully sent.
examples:
application/json: {}
schema:
type: object
"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

98
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,48 +29,71 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user who has started to type.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
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: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"typing": true,
"timeout": 30000
}
properties:
typing:
type: boolean
description: |-
Whether the user is typing or not. If `false`, the `timeout`
key can be omitted.
timeout:
type: integer
description: The length of time in milliseconds to mark this user as typing.
required: ["typing"]
properties:
typing:
type: boolean
description: |-
Whether the user is typing or not. If `false`, the `timeout`
key can be omitted.
timeout:
type: integer
description: The length of time in milliseconds to mark this user as typing.
required:
- typing
description: The current typing state.
required: true
responses:
200:
"200":
description: The new typing state was set.
examples:
application/json: {
}
schema:
type: object # empty json object
429:
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
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

163
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,67 +33,93 @@ paths:
operationId: searchUserDirectory
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
search_term:
type: string
description: The term to search for
example: "foo"
limit:
type: integer
description: The maximum number of results to return. Defaults to 10.
example: 10
required: ["search_term"]
requestBody:
content:
application/json:
schema:
type: object
properties:
search_term:
type: string
description: The term to search for
example: foo
limit:
type: integer
description: The maximum number of results to return. Defaults to 10.
example: 10
required:
- search_term
required: true
responses:
200:
"200":
description: The results of the search.
examples:
application/json: {
"results": [
{
"user_id": "@foo:bar.com",
"display_name": "Foo",
"avatar_url": "mxc://bar.com/foo"
}
],
"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:
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:
response:
value: {
"results": [
{
"user_id": "@foo:bar.com",
"display_name": "Foo",
"avatar_url": "mxc://bar.com/foo"
}
],
"limited": false
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

86
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,33 +40,52 @@ 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
}
}
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions
unstable_features:
content:
application/json:
schema:
type: object
description: |-
Experimental features the server supports. Features not listed here,
or the lack of this property all together, indicate that a feature is
not supported.
additionalProperties:
type: boolean
description: Whether or not the namespaced feature is supported.
required: ['versions']
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions
unstable_features:
type: object
description: |-
Experimental features the server supports. Features not listed here,
or the lack of this property all together, indicate that a feature is
not supported.
additionalProperties:
type: boolean
description: Whether or not the namespaced feature is supported.
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

111
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,42 +26,64 @@ 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
}
schema:
type: object
properties:
username:
type: string
description: |-
The username to use.
password:
type: string
description: |-
The password to use.
uris:
type: array
items:
type: string
description: A list of TURN URIs
ttl:
type: integer
description: The time-to-live in seconds
required: ["username", "password", "uris", "ttl"]
429:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: The username to use.
password:
type: string
description: The password to use.
uris:
type: array
items:
type: string
description: A list of TURN URIs
ttl:
type: integer
description: The time-to-live in seconds
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.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

36
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.
schema:
"$ref": "definitions/wellknown/full.yaml"
404:
content:
application/json:
schema:
$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

149
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,61 +31,85 @@ 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"
}
schema:
type: object
required: ["user_id"]
properties:
user_id:
type: string
description: The user ID that owns the access token.
device_id:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Device ID associated with the access token. If no device
is associated with the access token (such as in the case
of application services) then this field can be omitted.
Otherwise this is required.
is_guest:
x-addedInMatrixVersion: "1.2"
type: boolean
description: |-
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: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description:
The appservice cannot masquerade as the user or has not registered them.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Application service has not registered this user."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
"200":
description: The token belongs to a known user.
content:
application/json:
schema:
type: object
required:
- user_id
properties:
user_id:
type: string
description: The user ID that owns the access token.
device_id:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Device ID associated with the access token. If no device
is associated with the access token (such as in the case
of application services) then this field can be omitted.
Otherwise this is required.
is_guest:
x-addedInMatrixVersion: "1.2"
type: boolean
description: |-
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.
examples:
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
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Application service has not registered this user."
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$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

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

@ -12,102 +12,108 @@
# 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
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
200:
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
example: monkeys_are_GREAT
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
format: int64
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
type: string
responses:
"200":
description: Validation information for the session.
content:
application/json:
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
format: int64
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
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`.
examples:
application/json: {
"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:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"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"
"/3pid/bind":
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"
}
"404":
description: The Session ID or client secret were not found.
content:
application/json:
schema:
$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,119 +129,136 @@ paths:
operationId: bindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required: ["sid", "client_secret", "mxid"]
responses:
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"
}
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
format: int64
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.
ts:
type: integer
format: int64
description: The unix timestamp at which the association was verified.
signatures:
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required:
- sid
- client_secret
- mxid
responses:
"200":
description: The association was published.
content:
application/json:
schema:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
400:
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
format: int64
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.
ts:
type: integer
format: int64
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
allOf:
- $ref: ../../schemas/server-signatures.yaml
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
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`.
examples:
application/json: {
"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:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"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"
"/3pid/unbind":
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"
}
"404":
description: The Session ID or client secret were not found
content:
application/json:
schema:
$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,65 +280,67 @@ paths:
operationId: unbindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
}
}
}
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required:
- medium
- address
required:
- threepid
- mxid
responses:
200:
"200":
description: The association was successfully removed.
examples:
application/json: {}
schema:
type: object
400:
content:
application/json:
schema:
type: object
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.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
501:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
"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

186
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,64 +24,74 @@ 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
schema:
$ref: "../client-server/definitions/openid_token.yaml"
requestBody:
content:
application/json:
schema:
$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"
}
schema:
type: object
properties:
token:
type: string
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
required: ['token']
"/account":
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
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"
}
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
required: ['user_id']
403:
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
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).
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"
"/account/logout":
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"
}
/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: {}
schema:
type: object
401:
description: |-
The token is not registered or is otherwise unknown to the server.
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
type: object
examples:
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"
}
"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"
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"
}
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

239
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
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
responses:
200:
"200":
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
content:
application/json:
schema:
$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.
examples:
application/json: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
"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"
"/validate/email/submitToken":
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"
}
/validate/email/submitToken:
post:
summary: Validate ownership of an email address.
description: |-
@ -110,53 +108,63 @@ paths:
operationId: emailSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
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"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
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
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
"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
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).
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"
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"
}
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
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
example: monkeys_are_GREAT
schema:
type: string
- in: query
type: string
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

184
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,76 +28,108 @@ paths:
operationId: blindlySignStuffV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
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"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
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
responses:
200:
"200":
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
content:
application/json:
schema:
type: object
description: The signature of the mxid, sender, and token.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"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:
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
type: object
description: The signature of the mxid, sender, and token.
allOf:
- $ref: ../../schemas/server-signatures.yaml
token:
type: string
description: The token for the invitation.
required:
- mxid
- sender
- signatures
- token
examples:
response:
value: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
"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"
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"
}
"404":
description: The token was not found.
content:
application/json:
schema:
$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

231
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,33 +29,39 @@ paths:
operationId: getHashDetails
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The hash function information.
examples:
application/json: {
"lookup_pepper": "matrixrocks",
"algorithms": ["none", "sha256"]
}
schema:
type: object
properties:
lookup_pepper:
type: string
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the `/lookup` endpoint when performing lookups.
content:
application/json:
schema:
type: object
properties:
lookup_pepper:
type: string
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the `/lookup` endpoint when performing lookups.
Servers SHOULD rotate this string often.
algorithms:
type: array
items:
type: string
description: |-
The algorithms the server supports. Must contain at least `sha256`.
required: ['lookup_pepper', 'algorithms']
"/lookup":
Servers SHOULD rotate this string often.
algorithms:
type: array
items:
type: string
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,78 +71,95 @@ paths:
operationId: lookupUsersV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
algorithm:
type: string
description: |-
The algorithm the client is using to encode the `addresses`. This
should be one of the available options from `/hash_details`.
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"
addresses:
type: array
items:
requestBody:
content:
application/json:
schema:
type: object
properties:
algorithm:
type: string
description: |-
The addresses to look up. The format of the entries here depend on
the `algorithm` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
description: |-
The algorithm the client is using to encode the `addresses`. This
should be one of the available options from `/hash_details`.
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
addresses:
type: array
items:
type: string
description: |-
The addresses to look up. The format of the entries here depend on
the `algorithm` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
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']
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
responses:
200:
description:
The associations for any matched `addresses`.
examples:
application/json: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
schema:
type: object
properties:
mappings:
"200":
description: The associations for any matched `addresses`.
content:
application/json:
schema:
type: object
description: |-
Any applicable mappings of `addresses` to Matrix User IDs. Addresses
which do not have associations will not be included, which can make
this property be an empty object.
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.
examples:
application/json: {
"errcode": "M_INVALID_PEPPER",
"error": "Unknown or invalid pepper - has it been rotated?"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
properties:
mappings:
type: object
description: |-
Any applicable mappings of `addresses` to Matrix User IDs. Addresses
which do not have associations will not be included, which can make
this property be an empty object.
title: AssociatedMappings
additionalProperties:
type: string
required:
- mappings
examples:
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?"
}
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

236
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
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
responses:
200:
"200":
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
content:
application/json:
schema:
$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.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
"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"
"/validate/msisdn/submitToken":
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"
}
/validate/msisdn/submitToken:
post:
summary: Validate ownership of a phone number.
description: |-
@ -112,53 +110,63 @@ paths:
operationId: msisdnSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
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"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
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
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
"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
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).
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"
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"
}
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
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
example: monkeys_are_GREAT
schema:
type: string
- in: query
type: string
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

40
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: {}
schema:
type: object
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

172
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"
}
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.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid":
"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
examples:
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"
}
/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"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
type: string
responses:
"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
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"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
type: string
responses:
"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
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

308
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,142 +52,176 @@ paths:
operationId: storeInviteV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:example.org"
room_avatar_url:
type: string
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"
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"
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"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
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"
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"]
requestBody:
content:
application/json:
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: email
address:
type: string
description: The email address of the invited user.
example: foo@example.com
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:example.org"
room_avatar_url:
type: string
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
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
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
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
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
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
responses:
200:
"200":
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: object
title: PublicKey
properties:
public_key:
type: string
description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url:
type: string
description: |
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']
display_name:
type: string
description: The generated (redacted) display name.
required: ['token', 'public_keys', 'display_name']
examples:
application/json: {
"token": "sometoken",
"public_keys": [
{
"public_key": "serverPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
},
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
400:
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: object
title: PublicKey
properties:
public_key:
type: string
description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url:
type: string
description: |
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
display_name:
type: string
description: The generated (redacted) display name.
required:
- token
- public_keys
- display_name
examples:
response:
value: {
"token": "sometoken",
"public_keys": [
{
"public_key": "serverPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
},
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
"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`.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
"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"
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"
}
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

223
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,81 +24,85 @@ 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:
description: |-
The terms of service offered by the server.
examples:
application/json: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
schema:
type: object
properties:
policies:
"200":
description: The terms of service offered by the server.
content:
application/json:
schema:
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:
properties:
policies:
type: object
title: Internationalised Policy
title: Policy Map
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']
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:
response:
value: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
post:
summary: Indicates acceptance of terms to the server.
description: |-
@ -126,24 +120,43 @@ paths:
operationId: agreeToTerms
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
user_accepts:
type: array
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']
requestBody:
content:
application/json:
schema:
type: object
properties:
user_accepts:
type: array
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
responses:
200:
description: |-
The server has considered the user as having accepted the provided URLs.
examples:
application/json: {}
schema:
type: object
"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

64
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,19 +30,39 @@ 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"]
}
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions.
required: ['versions']
content:
application/json:
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported 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

378
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,182 +39,203 @@ 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
schema:
type: object
example: {
"notification": {
"event_id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"content": {
"msgtype": "m.text",
"body": "I'm floating in a most peculiar way."
},
"counts": {
"unread" : 2,
"missed_calls": 1
},
"devices": [
{
"app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678,
"data" : {},
"tweaks": {
"sound": "bing"
requestBody:
content:
application/json:
schema:
type: object
example: {
"notification": {
"event_id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"content": {
"msgtype": "m.text",
"body": "I'm floating in a most peculiar way."
},
"counts": {
"unread": 2,
"missed_calls": 1
},
"devices": [
{
"app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678,
"data": {},
"tweaks": {
"sound": "bing"
}
}
}
]
]
}
}
}
required: ["notification"]
properties:
notification:
type: object
title: Notification
description: Information about the push notification
required: ["devices"]
properties:
event_id:
type: string
description: |-
The Matrix event ID of the event being notified about.
This is required if the notification is about a
particular Matrix event. It may be omitted for notifications
that only contain updated badge counts. This ID can and
should be used to detect duplicate notification requests.
room_id:
type: string
description: |-
The ID of the room in which this event occurred.
Required if the notification relates to a specific
Matrix event.
type:
type: string
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.
sender_display_name:
type: string
description: |-
The current display name of the sender in the room in which
the event occurred.
room_name:
type: string
description: The name of the room in which the event occurred.
room_alias:
type: string
description: An alias to display for the room in which the event occurred.
user_is_target:
type: boolean
description: |-
This is true if the user receiving the notification is the
subject of a member event (i.e. the `state_key` of the
member event is equal to the user's Matrix ID).
prio:
type: string
enum: ["high", "low"]
description: |-
The priority of the notification. If omitted, `high` is
assumed. This may be used by push gateways to deliver less
time-sensitive notifications in a way that will preserve
battery power on mobile devices.
content:
type: object
title: EventContent
description: |-
The `content` field from the event, if present. The pusher
may omit this if the event had no content or for any other
reason.
counts:
type: object
title: Counts
description: |-
This is a dictionary of the current number of unacknowledged
communications for the recipient user. Counts whose value is
zero should be omitted.
properties:
unread:
type: integer
description: |-
The number of unread messages a user has across all of the
rooms they are a member of.
missed_calls:
type: integer
description: |-
The number of unacknowledged missed calls a user has
across all rooms of which they are a member.
devices:
type: array
title: Devices
description: |-
This is an array of devices that the notification should be sent to.
items:
required:
- notification
properties:
notification:
type: object
title: Notification
description: Information about the push notification
required:
- devices
properties:
event_id:
type: string
description: |-
The Matrix event ID of the event being notified about.
This is required if the notification is about a
particular Matrix event. It may be omitted for notifications
that only contain updated badge counts. This ID can and
should be used to detect duplicate notification requests.
room_id:
type: string
description: |-
The ID of the room in which this event occurred.
Required if the notification relates to a specific
Matrix event.
type:
type: string
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.
sender_display_name:
type: string
description: |-
The current display name of the sender in the room in which
the event occurred.
room_name:
type: string
description: The name of the room in which the event occurred.
room_alias:
type: string
description: An alias to display for the room in which the event occurred.
user_is_target:
type: boolean
description: |-
This is true if the user receiving the notification is the
subject of a member event (i.e. the `state_key` of the
member event is equal to the user's Matrix ID).
prio:
type: string
enum:
- high
- low
description: |-
The priority of the notification. If omitted, `high` is
assumed. This may be used by push gateways to deliver less
time-sensitive notifications in a way that will preserve
battery power on mobile devices.
content:
type: object
title: Device
title: EventContent
description: |-
The `content` field from the event, if present. The pusher
may omit this if the event had no content or for any other
reason.
counts:
type: object
title: Counts
description: |-
This is a dictionary of the current number of unacknowledged
communications for the recipient user. Counts whose value is
zero should be omitted.
properties:
app_id:
type: string
description: |-
The `app_id` given when the pusher was created.
pushkey:
type: string
description: The `pushkey` given when the pusher was created.
pushkey_ts:
unread:
type: integer
format: int64
description: |-
The unix timestamp (in seconds) when the
pushkey was last updated.
data:
type: object
title: PusherData
The number of unread messages a user has across all of the
rooms they are a member of.
missed_calls:
type: integer
description: |-
A dictionary of additional pusher-specific data. For
'http' pushers, this is the data dictionary passed in at
pusher creation minus the `url` key.
tweaks:
type: object
title: Tweaks
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']
The number of unacknowledged missed calls a user has
across all rooms of which they are a member.
devices:
type: array
title: Devices
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.
pushkey:
type: string
description: The `pushkey` given when the pusher was created.
pushkey_ts:
type: integer
format: int64
description: |-
The unix timestamp (in seconds) when the
pushkey was last updated.
data:
type: object
title: PusherData
description: |-
A dictionary of additional pusher-specific data. For
'http' pushers, this is the data dictionary passed in at
pusher creation minus the `url` key.
tweaks:
type: object
title: Tweaks
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
description: Information about the push notification.
required: true
responses:
200:
"200":
description: A list of rejected push keys.
examples:
application/json: {
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
schema:
type: object # empty json object
properties:
rejected:
type: array
description: |-
A list of all pushkeys given in the notification request that
are not valid. These could have been rejected by an upstream
gateway because they have expired or have never been valid.
Homeservers must cease sending notification requests for these
pushkeys and remove the associated pushers. It may not
necessarily be the notification in the request that failed:
it could be that a previous notification to the same pushkey
failed. May be empty.
items:
type: string
description: A pushkey that has been rejected.
required: ['rejected']
content:
application/json:
schema:
type: object # empty json object
properties:
rejected:
type: array
description: |-
A list of all pushkeys given in the notification request that
are not valid. These could have been rejected by an upstream
gateway because they have expired or have never been valid.
Homeservers must cease sending notification requests for these
pushkeys and remove the associated pushers. It may not
necessarily be the notification in the request that failed:
it could be that a previous notification to the same pushkey
failed. May be empty.
items:
type: string
description: A pushkey that has been 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

168
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
type: array
items:
type: string
description: The event IDs to backfill from.
required: true
x-example: ["$abc123:matrix.org"]
example:
- $abc123:matrix.org
schema:
type: array
items:
type: string
- 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.
schema:
$ref: "definitions/unlimited_pdu_transaction.yaml"
content:
application/json:
schema:
$ref: definitions/unlimited_pdu_transaction.yaml
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
@ -86,58 +81,85 @@ 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: object
properties:
limit:
type: integer
description: The maximum number of events to retrieve. Defaults to 10.
example: 10
min_depth:
type: integer
description: The minimum depth of events to retrieve. Defaults to 0.
example: 0
earliest_events:
type: array
description: |-
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of `latest_events`.
items:
type: string
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']
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: The maximum number of events to retrieve. Defaults to 10.
example: 10
min_depth:
type: integer
description: The minimum depth of events to retrieve. Defaults to 0.
example: 0
earliest_events:
type: array
description: |-
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of `latest_events`.
items:
type: string
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
responses:
200:
"200":
description: |-
The previous events for `latest_events`, excluding any `earliest_events`, up to the
provided `limit`.
schema:
type: object
properties:
events:
type: array
description: |-
The missing events. The event format varies depending on the room version - check
the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
required: ['events']
examples:
application/json: {
"events": [
{"$ref": "examples/minimal_pdu.json"}
]
}
content:
application/json:
schema:
type: object
properties:
events:
type: array
description: |-
The missing events. The event format varies depending on the room version - check
the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
required:
- events
examples:
response:
value: {
"events": [
{
"$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

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

@ -56,20 +56,21 @@ properties:
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
depth:
type: integer
description: |-
@ -91,20 +92,21 @@ properties:
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
}
properties:
sha256:
type: string
description: The event hash.
example: Base64EncodedSha256HashesShouldBe43BytesLong
required: ['sha256']
redacts:
type: string
description: For redaction events, the ID of the event being redacted.

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

@ -11,60 +11,68 @@
# 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"
responses:
200:
description: The auth chain for the event.
example: $helloworld:example.org
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The [PDUs](/server-server-api/#pdus) forming the auth chain
of the given event. The event format varies depending on the
room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
properties: {}
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain']
type: string
responses:
"200":
description: The auth chain for the event.
content:
application/json:
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The [PDUs](/server-server-api/#pdus) forming the auth chain
of the given event. The event format varies depending on the
room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
properties: {}
example:
$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

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

@ -11,84 +11,80 @@
# 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.
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
pdus:
type: array
description: |-
The fully resolved state of the room at the given event. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
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.
properties: {}
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain', 'pdus']
content:
application/json:
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
properties: {}
example:
$ref: examples/minimal_pdu.json
pdus:
type: array
description: |-
The fully resolved state of the room at the given event. Note that
events have a different format depending on the room version -
check the [room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
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.
properties: {}
example:
$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,72 +98,84 @@ 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.
schema:
type: object
properties:
auth_chain_ids:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively.
items:
type: string
example: ["$an_event:example.org"]
pdu_ids:
type: array
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:
content:
application/json:
schema:
type: object
properties:
auth_chain_ids:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively.
items:
type: string
example:
- $an_event:example.org
pdu_ids:
type: array
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":
description: |-
The given `event_id` was not found or the server doesn't know about the state at
that event to return anything useful.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
}
schema:
"$ref": "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
}
"/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.
schema:
type: object
properties:
event_id:
type: string
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']
examples:
application/json: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
404:
description: |-
No event was found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
schema:
"$ref": "../client-server/definitions/errors/error.yaml"
"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
origin_server_ts:
type: integer
description: The event's timestamp, in milliseconds since the Unix epoch.
required:
- event_id
- origin_server_ts
examples:
response:
value: {
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653
}
"404":
description: No event was found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
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

257
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,134 +38,160 @@ 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:
allOf:
- $ref: "definitions/invite_event.yaml"
- type: object
properties:
unsigned:
type: object
title: UnsignedData
description: |-
Information included alongside the event that is not signed. May include more
than what is listed here.
properties:
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"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
type: string
requestBody:
content:
application/json:
schema:
allOf:
- $ref: definitions/invite_event.yaml
- type: object
properties:
unsigned:
type: object
title: UnsignedData
description: |-
Information included alongside the event that is not signed. May include more
than what is listed here.
properties:
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
example:
$ref: ../../event-schemas/examples/invite_room_state.json
type: object
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
}
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.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value `200`.
example: 200
- type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
examples:
application/json: [
200,
{
"event": {
"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",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
- type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: definitions/invite_event.yaml
required:
- event
examples:
response:
value: [
200,
{
"event": {
"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",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
]
},
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
}
]
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.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
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/v1
components:
securitySchemes:
$ref: definitions/security.yaml

278
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,101 +42,51 @@ 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: object
properties:
room_version:
type: string
description: The version of the room where the user is being invited to.
example: "2"
event:
$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"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
required: ['room_version', 'event']
example: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
}
responses:
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.
schema:
type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
examples:
application/json: {
"event": {
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
room_version:
type: string
description: The version of the room where the user is being invited to.
example: "2"
event:
$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
example:
$ref: ../../event-schemas/examples/invite_room_state.json
required:
- room_version
- event
example: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": {
"membership": "invite"
},
@ -155,27 +94,71 @@ paths:
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
}
403:
required: true
responses:
"200":
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:
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
examples:
response:
value: {
"event": {
"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",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
}
"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,19 +166,54 @@ paths:
The error should be passed through to clients so that they
may give better feedback to users.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
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

560
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,118 +29,128 @@ 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.**
schema:
type: object
properties:
room_version:
type: string
description: |-
The version of the room where the server is trying to join. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. 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
title: Event Template
properties:
sender:
room_version:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
description: |-
The version of the room where the server is trying to join. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
title: Event Template
properties:
membership:
sender:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
description: The name of the resident homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
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:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
examples:
application/json: {
"room_version": "2",
"event": {
"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"
}
}
}
400:
An arbitrary user ID belonging to the resident server in
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:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
examples:
response:
value: {
"room_version": "2",
"event": {
"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"
}
}
}
"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,45 +176,53 @@ paths:
resident server would be unable to meet the auth rules governing
`join_authorised_via_users_server` on the resulting `m.room.member`
event.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"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"
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
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 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:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
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"
}
"404":
description: |-
The room that the joining server is attempting to join is unknown
to the receiving server.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
"/send_join/{roomId}/{eventId}":
put:
deprecated: true
@ -237,150 +244,167 @@ 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: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
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.
An arbitrary user ID belonging to the resident server in
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.
The resident server which owns the provided user ID must have a
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:
- state_key
- sender
- origin
- 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"
}
}
The resident server which owns the provided user ID must have a
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:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
required: true
responses:
200:
description: |-
The join event has been accepted into the room.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
"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
- type: object
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
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: |-
The resolved current room state prior to the join event.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
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.
state:
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
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"]
examples:
application/json: [
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"}
}
]
The event format varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
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.
required:
- auth_chain
- state
- origin
examples:
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"
}
}
]
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

398
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,83 +73,180 @@ 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: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: boolean
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
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.
The resident server which owns the provided user ID must have a
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:
- state_key
- sender
- origin
- 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.
content:
application/json:
schema:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
origin:
type: string
description: The resident server's DNS name.
members_omitted:
type: boolean
description: "`true` if `m.room.member` events have been omitted from `state`."
x-addedInMatrixVersion: "1.6"
auth_chain:
type: array
description: |-
All events in the auth chain for the new join event, as well
as those in the auth chains for any events returned in
`state`.
If the `omit_members` query parameter was set to `true`, then
any events that are returned in `state` may be omitted from
`auth_chain`, whether or not membership events are omitted
from `state`.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
`state`, and to allow elision of redundant events.
state:
type: array
description: |-
The resolved current room state prior to the join event.
If the request had `omit_members` set to `true`, events of
type `m.room.member` may be omitted from the response to
reduce the size of the response. If this is done,
`members_omitted` must be set to `true`.
items:
type: object
title: PDU
x-changedInMatrixVersion:
"1.6": permit omission of membership events.
event:
type: object
title: SignedMembershipEvent
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed
copy of the membership event sent to other servers by the resident server, including the resident
server's signature.
servers_in_room:
type: array
x-addedInMatrixVersion: "1.6"
description: |-
**Required** if `members_omitted` is true.
An arbitrary user ID belonging to the resident server in
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.
The resident server which owns the provided user ID must have a
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:
- state_key
- sender
- origin
- 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"
}
}
responses:
400:
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
examples:
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"
]
}
"400":
description: |-
The request is invalid in some way.
@ -182,103 +269,42 @@ paths:
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"
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.
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.
schema:
type: object
properties:
origin:
type: string
description: The resident server's DNS name.
members_omitted:
type: boolean
description: "`true` if `m.room.member` events have been omitted from `state`."
x-addedInMatrixVersion: "1.6"
auth_chain:
type: array
description: |-
All events in the auth chain for the new join event, as well
as those in the auth chains for any events returned in
`state`.
If the `omit_members` query parameter was set to `true`, then
any events that are returned in `state` may be omitted from
`auth_chain`, whether or not membership events are omitted
from `state`.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
`state`, and to allow elision of redundant events.
state:
type: array
description: |-
The resolved current room state prior to the join event.
If the request had `omit_members` set to `true`, events of
type `m.room.member` may be omitted from the response to
reduce the size of the response. If this is done,
`members_omitted` must be set to `true`.
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
permit omission of membership events.
event:
type: object
title: SignedMembershipEvent
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed
copy of the membership event sent to other servers by the resident server, including the resident
server's signature.
servers_in_room:
type: array
x-addedInMatrixVersion: "1.6"
description: |-
**Required** if `members_omitted` is true.
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"]
examples:
application/json: {
"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"]
}
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

139
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,88 +26,106 @@ 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.
schema:
$ref: "definitions/keys_query_response.yaml"
"/query":
content:
application/json:
schema:
$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
schema:
type: object
example: {
"server_keys": {
"example.org": {
"ed25519:abc123": {
"minimum_valid_until_ts": 1234567890
requestBody:
content:
application/json:
schema:
type: object
example: {
"server_keys": {
"example.org": {
"ed25519:abc123": {
"minimum_valid_until_ts": 1234567890
}
}
}
}
}
properties:
server_keys:
type: object
description: |-
The query criteria. The outer `string` key on the object is the
server name (eg: `matrix.org`). The inner `string` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty `server_keys`
array in the response.
The notary server may return multiple keys regardless of the Key IDs
given.
additionalProperties:
properties:
server_keys:
type: object
name: ServerName
description: The server names to query.
description: |-
The query criteria. The outer `string` key on the object is the
server name (eg: `matrix.org`). The inner `string` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty `server_keys`
array in the response.
The notary server may return multiple keys regardless of the Key IDs
given.
additionalProperties:
type: object
title: Query Criteria
description: The server key IDs to query.
properties:
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.
description: The server names to query.
additionalProperties:
type: object
title: Query Criteria
description: The server key IDs to query.
properties:
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.
example: 1234567890
required: ['server_keys']
If not supplied, the current time as determined by the notary
server is used.
example: 1234567890
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.
schema:
$ref: "definitions/keys_query_response.yaml"
content:
application/json:
schema:
$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

35
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
schema:
$ref: "definitions/keys.yaml"
content:
application/json:
schema:
$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

493
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,107 +29,115 @@ 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"
- 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.
description: The room versions the sending server has support for.
required: true # knocking was supported in v7
x-example: ["1", "7"]
example:
- "1"
- "7"
schema:
type: array
items:
type: string
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.**
schema:
type: object
properties:
room_version:
type: string
description: |-
The version of the room where the server is trying to knock.
example: "7"
event:
description: |-
An unsigned template event. 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
title: Event Template
properties:
sender:
room_version:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
description: The version of the room where the server is trying to knock.
example: "7"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "knock"}
title: Event Template
properties:
membership:
sender:
type: string
description: The value `knock`.
example: "knock"
required: ['membership']
description: The user ID of the knocking member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: knock
properties:
membership:
type: string
description: The value `knock`.
example: knock
required:
- membership
required:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
required:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
required:
- room_version # knocking was added in v7
- event
examples:
application/json: {
"room_version": "7",
"event": {
"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": "knock"
}
}
}
400:
- room_version # knocking was added in v7
- event
examples:
response:
value: {
"room_version": "7",
"event": {
"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": "knock"
}
}
}
"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,47 +145,55 @@ paths:
The error should be passed through to clients so that they
may give better feedback to users.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"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:
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
response:
value: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to knock on this room",
"room_version": "7"
}
"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.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room",
}
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"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,117 +212,147 @@ 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: object
properties:
sender:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
origin:
type: string
description: The name of the knocking homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the knocking homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "knock"}
properties:
membership:
type: string
description: The value `knock`.
example: "knock"
required: ['membership']
required:
- state_key
- sender
- origin
- 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": "knock"
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
origin:
type: string
description: The name of the knocking homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the knocking homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: knock
properties:
membership:
type: string
description: The value `knock`.
example: knock
required:
- membership
required:
- state_key
- sender
- origin
- 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": "knock"
}
}
}
required: true
responses:
200:
"200":
description: |-
Information about the room to pass along to clients regarding the
knock.
schema:
type: object
properties:
knock_room_state:
type: array
items:
$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']
examples:
application/json: {
"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:
content:
application/json:
schema:
type: object
properties:
knock_room_state:
type: array
items:
$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
examples:
response:
value: {
"knock_room_state": {
"$ref": "../../event-schemas/examples/knock_room_state.json"
}
}
"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.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room",
}
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"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

360
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,105 +29,115 @@ 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.**
schema:
type: object
properties:
room_version:
type: string
description: |-
The version of the room where the server is trying to leave. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. 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
title: Event Template
properties:
sender:
room_version:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
description: |-
The version of the room where the server is trying to leave. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
title: Event Template
properties:
membership:
sender:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
examples:
application/json: {
"room_version": "2",
"event": {
"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"
}
}
}
403:
description: |-
The request is not authorized. This could mean that the user is not in the room.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "User is not in the room."
}
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: leave
required:
- membership
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
examples:
response:
value: {
"room_version": "2",
"event": {
"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"
}
}
}
"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
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User is not in the room."
}
"/send_leave/{roomId}/{eventId}":
put:
deprecated: true
@ -160,93 +159,108 @@ 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: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- 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"
}
}
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: leave
required:
- membership
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- depth
- content
required: true
responses:
200:
"200":
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Empty Object
description: An empty object.
examples:
application/json: [200, {}]
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Empty Object
description: An empty object.
examples:
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

181
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,86 +44,108 @@ 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: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value `leave`.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- 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"
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: leave
required:
- membership
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- 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.
schema:
type: object
title: Empty Object
description: An empty object.
examples:
application/json: {}
content:
application/json:
schema:
type: object
title: Empty Object
description: An empty object.
examples:
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

78
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,29 +28,46 @@ 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.
schema:
type: object
properties:
sub:
type: string
description: The Matrix User ID who generated the token.
example: "@alice:example.com"
required: ['sub']
401:
"200":
description: Information about the user who generated the OpenID access token.
content:
application/json:
schema:
type: object
properties:
sub:
type: string
description: The Matrix User ID who generated the token.
example: "@alice:example.com"
required:
- sub
"401":
description: The token was not recognized or has expired.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Access token unknown or expired"
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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

281
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
type: integer
description: |-
The maximum number of rooms to return. Defaults to 0 (no limit).
x-example: 10
description: The maximum number of rooms to return. Defaults to 0 (no limit).
example: 10
schema:
type: integer
- 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,32 +77,27 @@ 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.
schema:
type: object
properties:
limit:
type: integer
description: |-
Limit the number of results returned.
since:
type: string
description: |-
A pagination token from a previous request, allowing servers
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.
filter:
type: object
title: "Filter"
description: |-
Filter to apply to the results.
properties:
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
description: Limit the number of results returned.
since:
type: string
description: |-
A pagination token from a previous request, allowing servers
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.
filter:
type: object
title: Filter
description: Filter to apply to the results.
properties:
generic_search_term:
type: string
description: |-
@ -122,85 +113,109 @@ paths:
for. To include rooms without a room type, specify `null` within this
list. When not specified, all applicable rooms (regardless of type)
are returned.
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
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.
example: "irc"
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"room_types": [null, "m.space"]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
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.
example: irc
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo",
"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.
schema:
type: object
description: A list of the rooms on the server.
required: ["chunk"]
properties:
chunk:
title: "PublicRoomsChunks"
type: array
description: A paginated chunk of public rooms.
items:
allOf:
- $ref: "../client-server/definitions/public_rooms_chunk.yaml"
- type: object
properties:
# Override description of join_rule
join_rule:
type: string
description: |-
The room's join rule. When not present, the room is assumed to
be `public`. Note that rooms with `invite` join rules are not
expected here, but rooms with `knock` rules are given their
near-public nature.
next_batch:
type: string
description: |-
A pagination token for the response. The absence of this token
means there are no more results to fetch and the client should
stop paginating.
prev_batch:
type: string
description: |-
A pagination token that allows fetching previous results. The
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
application/json: {
"chunk": [
{
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space"
}
],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
content:
application/json:
schema:
type: object
description: A list of the rooms on the server.
required:
- chunk
properties:
chunk:
title: PublicRoomsChunks
type: array
description: A paginated chunk of public rooms.
items:
allOf:
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
- type: object
properties:
# Override description of join_rule
join_rule:
type: string
description: |-
The room's join rule. When not present, the room is assumed to
be `public`. Note that rooms with `invite` join rules are not
expected here, but rooms with `knock` rules are given their
near-public nature.
next_batch:
type: string
description: |-
A pagination token for the response. The absence of this token
means there are no more results to fetch and the client should
stop paginating.
prev_batch:
type: string
description: |-
A pagination token that allows fetching previous results. The
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
response:
value: {
"chunk": [
{
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space"
}
],
"next_batch": "p190q",
"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

206
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,50 +55,57 @@ 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.
schema:
type: object
properties:
room_id:
type: string
description: The room ID mapped to the queried room alias.
x-example: "!roomid1234:example.org"
servers:
type: array
description: |-
An array of server names that are likely to hold the given room. This
list may or may not include the server answering the query.
items:
type: string
required:
- "room_id"
- "servers"
examples:
application/json: {
"room_id": "!roomid1234:example.org",
"servers": [
"example.org",
"example.com",
"another.example.com:8449",
]
}
404:
"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.
example: "!roomid1234:example.org"
servers:
type: array
description: |-
An array of server names that are likely to hold the given room. This
list may or may not include the server answering the query.
items:
type: string
required:
- room_id
- servers
examples:
response:
value: {
"room_id": "!roomid1234:example.org",
"servers": [
"example.org",
"example.com",
"another.example.com:8449"
]
}
"404":
description: The room alias was not found.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias not found."
}
"/query/profile":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room alias not found."
}
/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,32 +147,53 @@ 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`.
schema:
type: object
properties:
displayname:
type: string
description: |-
The display name of the user. May be omitted if the user does not have a
display name set.
x-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"
examples:
application/json: {
"displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
}
404:
content:
application/json:
schema:
type: object
properties:
displayname:
type: string
description: |-
The display name of the user. May be omitted if the user does not have a
display name set.
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.
example: mxc://matrix.org/MyC00lAvatar
examples:
response:
value: {
"displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
}
"404":
description: The user does not exist or does not have a profile.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "User does not exist."
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
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