Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-05-07 17:44:10 +02:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Upgrade Swagger data to OpenAPI 3.1 (#1310)

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

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

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

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

@ -11,21 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Application Service API" title: Matrix Application Service API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/ping": /ping:
post: post:
x-addedInMatrixVersion: "1.7" x-addedInMatrixVersion: "1.7"
summary: Ping the application service summary: Ping the application service
@ -39,10 +30,9 @@ paths:
operationId: ping operationId: ping
security: security:
- homeserverAccessToken: [] - homeserverAccessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
description: Ping body with optional transaction ID.
schema: schema:
type: object type: object
example: { example: {
@ -54,10 +44,29 @@ paths:
description: |- description: |-
A transaction ID for the ping, copied directly from the A transaction ID for the ping, copied directly from the
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call. `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
description: Ping body with optional transaction ID.
responses: responses:
200: "200":
description: The provided `hs_token` is valid and the ping request was successful. description: The provided `hs_token` is valid and the ping request was successful.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,25 +11,15 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Application Service API" title: Matrix Application Service API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/thirdparty/protocol/{protocol}": "/thirdparty/protocol/{protocol}":
get: 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: |- description: |-
This API is called by the homeserver when it wants to present clients This API is called by the homeserver when it wants to present clients
with specific information about the various third-party networks that with specific information about the various third-party networks that
@ -40,42 +30,53 @@ paths:
parameters: parameters:
- in: path - in: path
name: protocol name: protocol
type: string
description: The protocol ID. description: The protocol ID.
required: true required: true
x-example: "irc" example: irc
schema:
type: string
responses: responses:
200: "200":
description: The protocol was found and metadata returned. description: The protocol was found and metadata returned.
content:
application/json:
schema: schema:
$ref: definitions/protocol.yaml $ref: definitions/protocol.yaml
401: "401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
"404":
description: No protocol was found with the given path.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user/{protocol}": "/thirdparty/user/{protocol}":
get: get:
summary: Retrieve the Matrix User ID of a corresponding third-party user. summary: Retrieve the Matrix User ID of a corresponding third-party user.
@ -89,102 +90,126 @@ paths:
parameters: parameters:
- in: path - in: path
name: protocol name: protocol
type: string
description: The protocol ID. description: The protocol ID.
required: true required: true
x-example: irc example: irc
schema:
type: string
- in: query - in: query
name: fields... name: fields...
type: string
description: |- description: |-
One or more custom fields that are passed to the application One or more custom fields that are passed to the application
service to help identify the user. service to help identify the user.
schema:
type: string
responses: responses:
200: "200":
description: The Matrix User IDs found with the given parameters. description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema: schema:
$ref: definitions/user_batch.yaml $ref: definitions/user_batch.yaml
401: "401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
"404":
description: No users were found with the given parameters.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location/{protocol}": "/thirdparty/location/{protocol}":
get: get:
summary: Retrieve Matrix-side portal rooms leading to a third-party location. summary: Retrieve Matrix-side portal rooms leading to a third-party location.
description: |- description: Retrieve a list of Matrix portal rooms that lead to the matched
Retrieve a list of Matrix portal rooms that lead to the matched third-party location. third-party location.
operationId: queryLocationByProtocol operationId: queryLocationByProtocol
security: security:
- homeserverAccessToken: [] - homeserverAccessToken: []
parameters: parameters:
- in: path - in: path
name: protocol name: protocol
type: string
description: The protocol ID. description: The protocol ID.
required: true required: true
x-example: irc example: irc
schema:
type: string
- in: query - in: query
name: fields... name: fields...
type: string
description: |- description: |-
One or more custom fields that are passed to the application One or more custom fields that are passed to the application
service to help identify the third-party location. service to help identify the third-party location.
schema:
type: string
responses: responses:
200: "200":
description: At least one portal room was found. description: At least one portal room was found.
content:
application/json:
schema: schema:
$ref: definitions/location_batch.yaml $ref: definitions/location_batch.yaml
401: "401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
"404":
description: No mappings were found with the given parameters.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema: /thirdparty/location:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
get: get:
summary: Reverse-lookup third-party locations given a Matrix room alias. summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |- description: |-
@ -196,84 +221,118 @@ paths:
parameters: parameters:
- in: query - in: query
name: alias name: alias
type: string
description: The Matrix room alias to look up. description: The Matrix room alias to look up.
schema:
type: string
responses: responses:
200: "200":
description: |- description: All found third-party locations.
All found third-party locations. content:
application/json:
schema: schema:
$ref: definitions/location_batch.yaml $ref: definitions/location_batch.yaml
401: "401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
"404":
description: No mappings were found with the given parameters.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema: /thirdparty/user:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
get: get:
summary: Reverse-lookup third-party users given a Matrix User ID. summary: Reverse-lookup third-party users given a Matrix User ID.
description: |- description: Retrieve an array of third-party users from a Matrix User ID.
Retrieve an array of third-party users from a Matrix User ID.
operationId: queryUserByID operationId: queryUserByID
security: security:
- homeserverAccessToken: [] - homeserverAccessToken: []
parameters: parameters:
- in: query - in: query
name: userid name: userid
type: string
description: The Matrix User ID to look up. description: The Matrix User ID to look up.
schema:
type: string
responses: responses:
200: "200":
description: |- description: An array of third-party users.
An array of third-party users. content:
application/json:
schema: schema:
$ref: definitions/user_batch.yaml $ref: definitions/user_batch.yaml
401: "401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
404: examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"404":
description: No mappings were found with the given parameters. description: No mappings were found with the given parameters.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
} }
schema: servers:
$ref: ../client-server/definitions/errors/error.yaml - url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Application Service API" title: Matrix Application Service API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/rooms/{roomAlias}": "/rooms/{roomAlias}":
get: get:
@ -43,48 +32,75 @@ paths:
parameters: parameters:
- in: path - in: path
name: roomAlias name: roomAlias
type: string
description: The room alias being queried. description: The room alias being queried.
required: true required: true
x-example: "#magicforest:example.com" example: "#magicforest:example.com"
schema:
type: string
responses: responses:
200: "200":
description: |- description: |-
The application service indicates that this room alias exists. The The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set information about the room such as its name and topic can be set
before responding. before responding.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
401: examples:
response:
value: {}
"401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
schema: "404":
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |- description: |-
The application service indicates that this room alias does not exist. The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Application Service API" title: Matrix Application Service API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/users/{userId}": "/users/{userId}":
get: get:
@ -43,45 +32,72 @@ paths:
parameters: parameters:
- in: path - in: path
name: userId name: userId
type: string
description: The user ID being queried. description: The user ID being queried.
required: true required: true
x-example: "@alice:example.com" example: "@alice:example.com"
schema:
type: string
responses: responses:
200: "200":
description: |- description: |-
The application service indicates that this user exists. The application The application service indicates that this user exists. The application
service MUST create the user using the client-server API. service MUST create the user using the client-server API.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
401: examples:
response:
value: {}
"401":
description: |- description: |-
The homeserver has not supplied credentials to the application service. The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
} }
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples: examples:
application/json: { response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
} }
schema: "404":
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |- description: |-
The application service indicates that this user does not exist. The application service indicates that this user does not exist.
Optional error information can be included in the body of this response. Optional error information can be included in the body of this response.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,19 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Application Service API" title: Matrix Application Service API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/transactions/{txnId}": "/transactions/{txnId}":
put: put:
@ -42,35 +33,59 @@ paths:
parameters: parameters:
- in: path - in: path
name: txnId name: txnId
type: string
description: |- description: |-
The transaction ID for this set of events. Homeservers generate The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests. these IDs and they are used to ensure idempotency of requests.
required: true required: true
x-example: "35" example: "35"
- in: body schema:
name: body type: string
description: Transaction information requestBody:
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
"events": [ "events": [
{"$ref": "../../event-schemas/examples/m.room.member.yaml"}, {
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} "$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
] ]
} }
properties: properties:
events: events:
type: array type: array
description: |- description: A list of events, formatted as per the Client-Server API.
A list of events, formatted as per the Client-Server API.
items: items:
$ref: "../client-server/definitions/client_event.yaml" $ref: ../client-server/definitions/client_event.yaml
required: ["events"] required:
- events
description: Transaction information
responses: responses:
200: "200":
description: The transaction was processed successfully. description: The transaction was processed successfully.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Administration API" title: Matrix Client-Server Administration API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/admin/whois/{userId}": "/admin/whois/{userId}":
get: get:
@ -41,16 +30,58 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: userId name: userId
description: The user to look up. description: The user to look up.
required: true required: true
x-example: "@peter:rabbit.rocks" example: "@peter:rabbit.rocks"
schema:
type: string
responses: responses:
200: "200":
description: The lookup was successful. description: The lookup was successful.
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one
login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
examples: examples:
application/json: { response:
value: {
"user_id": "@peter:rabbit.rocks", "user_id": "@peter:rabbit.rocks",
"devices": { "devices": {
"teapot": { "teapot": {
@ -73,43 +104,20 @@ paths:
} }
} }
} }
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: |-
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
tags: tags:
- Server administration - Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,23 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Account Administrative Contact API" title: Matrix Client-Server Account Administrative Contact API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/account/3pid": /account/3pid:
get: get:
summary: Gets a list of a user's third-party identifiers. summary: Gets a list of a user's third-party identifiers.
description: |- description: |-
@ -44,19 +33,10 @@ paths:
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The lookup was successful. description: The lookup was successful.
examples: content:
application/json: { application/json:
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
schema: schema:
type: object type: object
properties: properties:
@ -69,7 +49,9 @@ paths:
medium: medium:
type: string type: string
description: The medium of the third-party identifier. description: The medium of the third-party identifier.
enum: ["email", "msisdn"] enum:
- email
- msisdn
address: address:
type: string type: string
description: The third-party identifier address. description: The third-party identifier address.
@ -82,10 +64,25 @@ paths:
added_at: added_at:
type: integer type: integer
format: int64 format: int64
description: description: The timestamp, in milliseconds, when the homeserver associated the
The timestamp, in milliseconds, when the homeserver third-party identifier with the user.
associated the third-party identifier with the user. required:
required: ['medium', 'address', 'validated_at', 'added_at'] - medium
- address
- validated_at
- added_at
examples:
response:
value: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
tags: tags:
- Account management - Account management
post: post:
@ -105,15 +102,14 @@ paths:
deprecated: true deprecated: true
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
type: object type: object
properties: properties:
three_pid_creds: three_pid_creds:
title: "ThreePidCredentials" title: ThreePidCredentials
type: object type: object
description: The third-party credentials to associate with the account. description: The third-party credentials to associate with the account.
properties: properties:
@ -132,8 +128,13 @@ paths:
sid: sid:
type: string type: string
description: The session identifier given by the identity server. description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"] required:
required: ["three_pid_creds"] - client_secret
- id_server
- id_access_token
- sid
required:
- three_pid_creds
example: { example: {
"three_pid_creds": { "three_pid_creds": {
"id_server": "matrix.org", "id_server": "matrix.org",
@ -142,13 +143,12 @@ paths:
"client_secret": "d0nt-T3ll" "client_secret": "d0nt-T3ll"
} }
} }
required: true
responses: responses:
200: "200":
description: The addition was successful. description: The addition was successful.
examples: content:
application/json: { application/json:
"submit_url": "https://example.org/path/to/submitToken"
}
schema: schema:
type: object type: object
properties: properties:
@ -168,19 +168,27 @@ paths:
verification will happen without the client's involvement verification will happen without the client's involvement
provided the homeserver advertises this specification version provided the homeserver advertises this specification version
in the `/versions` response (ie: r0.5.0). in the `/versions` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken" example: https://example.org/path/to/submitToken
403:
description: The credentials could not be verified with the identity server.
examples: examples:
application/json: { response:
value: {
"submit_url": "https://example.org/path/to/submitToken"
}
"403":
description: The credentials could not be verified with the identity server.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_AUTH_FAILED", "errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third-party credentials could not be verified by the identity server." "error": "The third-party credentials could not be verified by the identity server."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Account management - Account management
"/account/3pid/add": /account/3pid/add:
post: post:
summary: Adds contact information to the user's account. summary: Adds contact information to the user's account.
description: |- description: |-
@ -194,10 +202,9 @@ paths:
operationId: add3PID operationId: add3PID
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
type: object type: object
properties: properties:
@ -206,35 +213,44 @@ paths:
Additional authentication information for the Additional authentication information for the
user-interactive authentication API. user-interactive authentication API.
allOf: allOf:
- $ref: "definitions/auth_data.yaml" - $ref: definitions/auth_data.yaml
client_secret: client_secret:
type: string type: string
description: The client secret used in the session with the homeserver. description: The client secret used in the session with the homeserver.
example: "d0nt-T3ll" example: d0nt-T3ll
sid: sid:
type: string type: string
description: The session identifier given by the homeserver. description: The session identifier given by the homeserver.
example: "abc123987" example: abc123987
required: ["client_secret", "sid"] required:
- client_secret
- sid
required: true
responses: responses:
200: "200":
description: The addition was successful. description: The addition was successful.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
401: examples:
description: |- response:
The homeserver requires additional authentication information. value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema: schema:
"$ref": "definitions/auth_response.yaml" $ref: definitions/auth_response.yaml
429: "429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Account management - Account management
"/account/3pid/bind": /account/3pid/bind:
post: post:
summary: Binds a 3PID to the user's account through an Identity Service. summary: Binds a 3PID to the user's account through an Identity Service.
description: |- description: |-
@ -248,10 +264,9 @@ paths:
operationId: bind3PID operationId: bind3PID
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
type: object type: object
properties: properties:
@ -263,32 +278,41 @@ paths:
description: The identity server to use. description: The identity server to use.
id_access_token: id_access_token:
type: string type: string
description: |- description: An access token previously registered with the identity server.
An access token previously registered with the identity server.
sid: sid:
type: string type: string
description: The session identifier given by the identity server. description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"] required:
- client_secret
- id_server
- id_access_token
- sid
example: { example: {
"id_server": "example.org", "id_server": "example.org",
"id_access_token": "abc123_OpaqueString", "id_access_token": "abc123_OpaqueString",
"sid": "abc123987", "sid": "abc123987",
"client_secret": "d0nt-T3ll" "client_secret": "d0nt-T3ll"
} }
required: true
responses: responses:
200: "200":
description: The addition was successful. description: The addition was successful.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
429: examples:
response:
value: {}
"429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Account management - Account management
"/account/3pid/delete": /account/3pid/delete:
post: post:
summary: Deletes a third-party identifier from the user's account summary: Deletes a third-party identifier from the user's account
description: |- description: |-
@ -301,10 +325,9 @@ paths:
operationId: delete3pidFromAccount operationId: delete3pidFromAccount
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
type: object type: object
properties: properties:
@ -315,32 +338,37 @@ paths:
MUST use the `id_server` the identifier was added through. If the MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`. a `id_server_unbind_result` of `no-support`.
example: "example.org" example: example.org
medium: medium:
type: string type: string
description: The medium of the third-party identifier being removed. description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"] enum:
example: "email" - email
- msisdn
example: email
address: address:
type: string type: string
description: The third-party address being removed. description: The third-party address being removed.
example: "example@example.org" example: example@example.org
required: ['medium', 'address'] required:
- medium
- address
required: true
responses: responses:
200: "200":
description: |- description: |-
The homeserver has disassociated the third-party identifier from the The homeserver has disassociated the third-party identifier from the
user. user.
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
id_server_unbind_result: id_server_unbind_result:
type: string type: string
enum: enum:
# XXX: I don't know why, but the order matters here so that "no-support" - no-support
# doesn't become "no- support" by the renderer. - success
- "no-support"
- "success"
description: |- description: |-
An indicator as to whether or not the homeserver was able to unbind An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. `success` indicates that the the 3PID from the identity server. `success` indicates that the
@ -348,12 +376,12 @@ paths:
indicates that the identity server refuses to support the request indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to or the homeserver was not able to determine an identity server to
unbind from. unbind from.
example: "success" example: success
required: required:
- id_server_unbind_result - id_server_unbind_result
tags: tags:
- Account management - Account management
"/account/3pid/unbind": /account/3pid/unbind:
post: post:
summary: Removes a user's third-party identifier from an identity server. summary: Removes a user's third-party identifier from an identity server.
description: |- description: |-
@ -366,10 +394,9 @@ paths:
operationId: unbind3pidFromAccount operationId: unbind3pidFromAccount
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
type: object type: object
properties: properties:
@ -380,46 +407,52 @@ paths:
MUST use the `id_server` the identifier was added through. If the MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`. a `id_server_unbind_result` of `no-support`.
example: "example.org" example: example.org
medium: medium:
type: string type: string
description: The medium of the third-party identifier being removed. description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"] enum:
example: "email" - email
- msisdn
example: email
address: address:
type: string type: string
description: The third-party address being removed. description: The third-party address being removed.
example: "example@example.org" example: example@example.org
required: ['medium', 'address'] required:
- medium
- address
required: true
responses: responses:
200: "200":
description: |- description: |-
The identity server has disassociated the third-party identifier from the The identity server has disassociated the third-party identifier from the
user. user.
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
id_server_unbind_result: id_server_unbind_result:
type: string type: string
enum: enum:
# XXX: I don't know why, but the order matters here so that "no-support" - no-support
# doesn't become "no- support" by the renderer. - success
- "no-support"
- "success"
description: |- description: |-
An indicator as to whether or not the identity server was able to unbind 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 the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine refuses to support the request or the homeserver was not able to determine
an identity server to unbind from. an identity server to unbind from.
example: "success" example: success
required: required:
- id_server_unbind_result - id_server_unbind_result
tags: tags:
- Account management - Account management
"/account/3pid/email/requestToken": /account/3pid/email/requestToken:
post: 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: |- description: |-
The homeserver must check that the given email address is **not** The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should 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 the email itself, either by sending a validation email itself or by using
a service it has control over. a service it has control over.
operationId: requestTokenTo3PIDEmail operationId: requestTokenTo3PIDEmail
parameters: requestBody:
- in: body content:
name: body application/json:
required: true
schema: schema:
$ref: "definitions/request_email_validation.yaml" $ref: definitions/request_email_validation.yaml
required: true
responses: responses:
200: "200":
description: |- description: |-
An email was sent to the given address. Note that this may be an 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 email containing the validation token or it may be informing the
user of an error. user of an error.
content:
application/json:
schema: schema:
$ref: "definitions/request_token_response.yaml" $ref: definitions/request_token_response.yaml
403: "400":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |- description: |-
The third-party identifier is already in use on the homeserver, or The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED` the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server can be returned if the server does not trust/support the identity server
provided in the request. provided in the request.
content:
application/json:
schema: schema:
$ref: "definitions/errors/error.yaml" $ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_THREEPID_IN_USE", "errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already 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: tags:
- Account management - Account management
"/account/3pid/msisdn/requestToken": /account/3pid/msisdn/requestToken:
post: 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: |- description: |-
The homeserver must check that the given phone number is **not** The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should 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 the phone number itself, either by sending a validation message itself or by using
a service it has control over. a service it has control over.
operationId: requestTokenTo3PIDMSISDN operationId: requestTokenTo3PIDMSISDN
parameters: requestBody:
- in: body content:
name: body application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses: responses:
200: "200":
description: An SMS message was sent to the given phone number. description: An SMS message was sent to the given phone number.
content:
application/json:
schema: schema:
$ref: "definitions/request_token_response.yaml" $ref: definitions/request_token_response.yaml
403: "400":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |- description: |-
The third-party identifier is already in use on the homeserver, or The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED` the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server can be returned if the server does not trust/support the identity server
provided in the request. provided in the request.
content:
application/json:
schema: schema:
$ref: "definitions/errors/error.yaml" $ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_THREEPID_IN_USE", "errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already 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: tags:
- Account management - Account management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

@ -11,28 +11,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Application Service Room Directory API" title: Matrix Client-Server Application Service Room Directory API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
paths: paths:
"/directory/list/appservice/{networkId}/{roomId}": "/directory/list/appservice/{networkId}/{roomId}":
put: put:
summary: |- summary: Updates a room's visibility in the application service's room directory.
Updates a room's visibility in the application service's room directory.
description: |- description: |-
Updates the visibility of a given room on the application service's room Updates the visibility of a given room on the application service's room
directory. directory.
@ -46,43 +32,69 @@ paths:
operationId: updateAppserviceRoomDirectoryVisibility operationId: updateAppserviceRoomDirectoryVisibility
parameters: parameters:
- in: path - in: path
type: string
name: networkId name: networkId
description: |- description: |-
The protocol (network) ID to update the room list for. This would The protocol (network) ID to update the room list for. This would
have been provided by the application service as being listed as have been provided by the application service as being listed as
a supported protocol. a supported protocol.
required: true required: true
x-example: "irc" example: irc
- in: path schema:
type: string type: string
- in: path
name: roomId name: roomId
description: The room ID to add to the directory. description: The room ID to add to the directory.
required: true required: true
x-example: "!somewhere:example.org" example: "!somewhere:example.org"
- in: body schema:
name: body type: string
required: true requestBody:
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
visibility: visibility:
type: string type: string
enum: ["public", "private"] enum:
- public
- private
description: |- description: |-
Whether the room should be visible (public) in the directory Whether the room should be visible (public) in the directory
or not (private). or not (private).
example: "public" example: public
required: ['visibility'] required:
- visibility
required: true
security: security:
# again, this is the appservice's token - not a typical client's # again, this is the appservice's token - not a typical client's
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The room's directory visibility has been updated. description: The room's directory visibility has been updated.
content:
application/json:
schema: schema:
type: object type: object
examples: examples:
application/json: {} response:
value: {}
tags: tags:
- Application service room directory management - Application service room directory management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Room Banning API" title: Matrix Client-Server Room Banning API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/rooms/{roomId}/ban": "/rooms/{roomId}/ban":
post: post:
@ -41,14 +30,15 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) from which the user should be banned. description: The room identifier (not alias) from which the user should be banned.
required: true required: true
x-example: "!e42d8c:matrix.org" example: "!e42d8c:matrix.org"
- in: body schema:
name: body type: string
required: true requestBody:
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
@ -63,29 +53,37 @@ paths:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: string type: string
description: The reason the user has been banned. This will be supplied as the 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. `reason` on the target's updated
required: ["user_id"] [`m.room.member`](/client-server-api/#mroommember) event.
required:
- user_id
required: true
responses: responses:
200: "200":
description: The user has been kicked and banned from the room. description: The user has been kicked and banned from the room.
examples: content:
application/json: { application/json:
}
schema: schema:
type: object type: object
403: examples:
response:
value: {}
"403":
description: |- description: |-
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room. - The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room. - The banner's power level is insufficient to ban users from the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room." "error": "You do not have a high enough power level to ban from this room."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Room membership - Room membership
"/rooms/{roomId}/unban": "/rooms/{roomId}/unban":
@ -101,14 +99,16 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) from which the user should be unbanned. description: The room identifier (not alias) from which the user should be
required: true unbanned.
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true required: true
example: "!e42d8c:matrix.org"
schema:
type: string
requestBody:
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
@ -125,26 +125,48 @@ paths:
description: |- description: |-
Optional reason to be included as the `reason` on the subsequent Optional reason to be included as the `reason` on the subsequent
membership event. membership event.
required: ["user_id"] required:
- user_id
required: true
responses: responses:
200: "200":
description: The user has been unbanned from the room. description: The user has been unbanned from the room.
examples: content:
application/json: { application/json:
}
schema: schema:
type: object type: object
403: examples:
response:
value: {}
"403":
description: |- description: |-
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room. - The unbanner's power level is insufficient to unban users from the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room." "error": "You do not have a high enough power level to unban from this room."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Room membership - Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Capabilities API" title: Matrix Client-Server Capabilities API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/capabilities": /capabilities:
get: get:
summary: Gets information about the server's capabilities. summary: Gets information about the server's capabilities.
description: |- description: |-
@ -34,13 +25,61 @@ paths:
operationId: getCapabilities operationId: getCapabilities
security: security:
- accessToken: [] - accessToken: []
parameters: []
responses: responses:
200: "200":
description: description: The capabilities of the server.
The capabilities of the server. content:
application/json:
schema:
type: object
required:
- capabilities
properties:
capabilities:
type: object
title: Capabilities
description: |-
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
properties:
m.change_password:
type: object
description: Capability to indicate if the user can change their password.
title: ChangePasswordCapability
properties:
enabled:
type: boolean
description: True if the user can change their password, false otherwise.
example: false
required:
- enabled
m.room_versions:
type: object
description: The room versions the server supports.
title: RoomVersionsCapability
properties:
default:
type: string
description: The default room version the server is using for new rooms.
example: "1"
available:
type: object
description: A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum:
- stable
- unstable
description: The stability of the room version.
required:
- default
- available
examples: examples:
application/json: { response:
value: {
"capabilities": { "capabilities": {
"m.change_password": { "m.change_password": {
"enabled": false "enabled": false
@ -59,54 +98,26 @@ paths:
} }
} }
} }
schema: "429":
type: object
required: ["capabilities"]
properties:
capabilities:
type: object
title: Capabilities
description: |-
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
properties:
"m.change_password":
type: object
description: |-
Capability to indicate if the user can change their password.
title: ChangePasswordCapability
properties:
enabled:
type: boolean
description: |-
True if the user can change their password, false otherwise.
example: false
required: ['enabled']
"m.room_versions":
type: object
description: The room versions the server supports.
title: RoomVersionsCapability
properties:
default:
type: string
description: |-
The default room version the server is using for new rooms.
example: "1"
available:
type: object
description: |-
A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum: [stable, unstable]
description: The stability of the room version.
required: ['default', 'available']
429:
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Capabilities - Capabilities
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

File diff suppressed because it is too large Load diff

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

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

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Cross Signing API" title: Matrix Client-Server Cross Signing API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/keys/device_signing/upload": /keys/device_signing/upload:
post: post:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
summary: Upload cross-signing keys. summary: Upload cross-signing keys.
@ -38,18 +27,14 @@ paths:
operationId: uploadCrossSigningKeys operationId: uploadCrossSigningKeys
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: keys application/json:
description: |-
The keys to be published.
required: true
schema: schema:
type: object type: object
properties: properties:
master_key: master_key:
description: |- description: Optional. The user\'s master key.
Optional. The user\'s master key.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
self_signing_key: self_signing_key:
@ -73,7 +58,7 @@ paths:
Additional authentication information for the Additional authentication information for the
user-interactive authentication API. user-interactive authentication API.
allOf: allOf:
- $ref: "definitions/auth_data.yaml" - $ref: definitions/auth_data.yaml
example: { example: {
"auth": { "auth": {
"type": "example.type.foo", "type": "example.type.foo",
@ -82,16 +67,20 @@ paths:
}, },
"master_key": { "master_key": {
"user_id": "@alice:example.com", "user_id": "@alice:example.com",
"usage": ["master"], "usage": [
"master"
],
"keys": { "keys": {
"ed25519:base64+master+public+key": "base64+master+public+key", "ed25519:base64+master+public+key": "base64+master+public+key"
} }
}, },
"self_signing_key": { "self_signing_key": {
"user_id": "@alice:example.com", "user_id": "@alice:example.com",
"usage": ["self_signing"], "usage": [
"self_signing"
],
"keys": { "keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
}, },
"signatures": { "signatures": {
"@alice:example.com": { "@alice:example.com": {
@ -101,9 +90,11 @@ paths:
}, },
"user_signing_key": { "user_signing_key": {
"user_id": "@alice:example.com", "user_id": "@alice:example.com",
"usage": ["user_signing"], "usage": [
"user_signing"
],
"keys": { "keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
}, },
"signatures": { "signatures": {
"@alice:example.com": { "@alice:example.com": {
@ -112,13 +103,17 @@ paths:
} }
} }
} }
description: The keys to be published.
required: true
responses: responses:
200: "200":
description: The provided keys were successfully uploaded. description: The provided keys were successfully uploaded.
content:
application/json:
schema: schema:
type: object type: object
example: {} example: {}
400: "400":
description: |- description: |-
The input was invalid in some way. This can include one of the The input was invalid in some way. This can include one of the
following error codes: following error codes:
@ -126,16 +121,20 @@ paths:
* `M_INVALID_SIGNATURE`: For example, the self-signing or * `M_INVALID_SIGNATURE`: For example, the self-signing or
user-signing key had an incorrect signature. user-signing key had an incorrect signature.
* `M_MISSING_PARAM`: No master key is available. * `M_MISSING_PARAM`: No master key is available.
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
"errcode": "M_INVALID_SIGNATURE", "errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature" "error": "Invalid signature"
} }
403: "403":
description: |- description: |-
The public key of one of the keys is the same as one of the user\'s 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. device IDs, or the request is not authorized for any other reason.
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
@ -144,7 +143,7 @@ paths:
} }
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/signatures/upload": /keys/signatures/upload:
post: post:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
summary: Upload cross-signing signatures. summary: Upload cross-signing signatures.
@ -158,13 +157,9 @@ paths:
operationId: uploadCrossSigningSignatures operationId: uploadCrossSigningSignatures
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: signatures application/json:
description: |-
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
schema: schema:
type: object type: object
title: Signatures title: Signatures
@ -193,7 +188,9 @@ paths:
}, },
"base64+master+public+key": { "base64+master+public+key": {
"user_id": "@alice:example.com", "user_id": "@alice:example.com",
"usage": ["master"], "usage": [
"master"
],
"keys": { "keys": {
"ed25519:base64+master+public+key": "base64+master+public+key" "ed25519:base64+master+public+key": "base64+master+public+key"
}, },
@ -210,7 +207,9 @@ paths:
"keys": { "keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
}, },
"usage": ["master"], "usage": [
"master"
],
"signatures": { "signatures": {
"@alice:example.com": { "@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
@ -219,9 +218,15 @@ paths:
} }
} }
} }
description: |-
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
responses: responses:
200: "200":
description: The provided signatures were processed. description: The provided signatures were processed.
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -236,13 +241,25 @@ paths:
additionalProperties: additionalProperties:
type: object type: object
title: Error title: Error
example: { example:
"@alice:example.com": { "@alice:example.com":
"HIJKLMN": { HIJKLMN:
"errcode": "M_INVALID_SIGNATURE", errcode: M_INVALID_SIGNATURE
"error": "Invalid signature" error: Invalid signature
}
}
}
tags: tags:
- End-to-end encryption - 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 the power level event the user needs a minimum power level for. Fields
must be specified under the `notifications` property in the power level must be specified under the `notifications` property in the power level
event's `content`. event's `content`.
x-example: content.body example: content.body
pattern: pattern:
type: string type: string
description: |- description: |-

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

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

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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Directory API" title: Matrix Client-Server Directory API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/directory/room/{roomAlias}": "/directory/room/{roomAlias}":
put: put:
@ -35,52 +24,64 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomAlias name: roomAlias
description: | description: |
The room alias to set. Its format is defined The room alias to set. Its format is defined
[in the appendices](/appendices/#room-aliases). [in the appendices](/appendices/#room-aliases).
required: true required: true
x-example: "#monkeys:matrix.org" example: "#monkeys:matrix.org"
- in: body schema:
name: body type: string
description: Information about this room alias. requestBody:
required: true content:
application/json:
schema: schema:
type: object type: object
properties: properties:
room_id: room_id:
type: string type: string
description: The room ID to set. description: The room ID to set.
required: ['room_id'] required:
- room_id
example: { example: {
"room_id": "!abnjk1jdasj98:capuchins.com" "room_id": "!abnjk1jdasj98:capuchins.com"
} }
description: Information about this room alias.
required: true
responses: responses:
200: "200":
description: The mapping was created. description: The mapping was created.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
400:
description: The given `roomAlias` is not a valid room alias.
examples: examples:
application/json: { response:
value: {}
"400":
description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM", "errcode": "M_INVALID_PARAM",
"error": "Room alias invalid" "error": "Room alias invalid"
} }
schema: "409":
"$ref": "definitions/errors/error.yaml"
409:
description: A room alias with that name already exists. description: A room alias with that name already exists.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_UNKNOWN", "errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists." "error": "Room alias #monkeys:matrix.org already exists."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Room directory - Room directory
get: get:
@ -91,20 +92,22 @@ paths:
The server will use the federation API to resolve the alias if the 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 part of the alias does not correspond to the server's own
domain. domain.
operationId: getRoomIdByAlias operationId: getRoomIdByAlias
parameters: parameters:
- in: path - in: path
type: string
name: roomAlias name: roomAlias
description: | description: |
The room alias. Its format is defined The room alias. Its format is defined
[in the appendices](/appendices/#room-aliases). [in the appendices](/appendices/#room-aliases).
required: true required: true
x-example: "#monkeys:matrix.org" example: "#monkeys:matrix.org"
schema:
type: string
responses: responses:
200: "200":
description: The room ID and other information for this alias. description: The room ID and other information for this alias.
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -118,7 +121,8 @@ paths:
type: string type: string
description: A server which is aware of this room alias. description: A server which is aware of this room alias.
examples: examples:
application/json: { response:
value: {
"room_id": "!abnjk1jdasj98:capuchins.com", "room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [ "servers": [
"capuchins.com", "capuchins.com",
@ -126,24 +130,30 @@ paths:
"another.com" "another.com"
] ]
} }
400: "400":
description: The given `roomAlias` is not a valid room alias. description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_INVALID_PARAM", "errcode": "M_INVALID_PARAM",
"error": "Room alias invalid" "error": "Room alias invalid"
} }
schema: "404":
"$ref": "definitions/errors/error.yaml"
404:
description: There is no mapped room ID for this room alias. description: There is no mapped room ID for this room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
value: {
"errcode": "M_NOT_FOUND", "errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found." "error": "Room alias #monkeys:matrix.org not found."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Room directory - Room directory
delete: delete:
@ -160,36 +170,41 @@ paths:
canonical alias event are recommended to, in addition to their other relevant permission 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 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. have permission to update the `m.room.canonical_alias` event.
operationId: deleteRoomAlias operationId: deleteRoomAlias
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomAlias name: roomAlias
description: | description: |
The room alias to remove. Its format is defined The room alias to remove. Its format is defined
[in the appendices](/appendices/#room-aliases). [in the appendices](/appendices/#room-aliases).
required: true required: true
x-example: "#monkeys:matrix.org" example: "#monkeys:matrix.org"
schema:
type: string
responses: responses:
200: "200":
description: The mapping was deleted. description: The mapping was deleted.
examples: content:
application/json: { application/json:
}
schema: schema:
type: object type: object
404:
description: There is no mapped room ID for this room alias.
examples: examples:
application/json: { response:
value: {}
"404":
description: There is no mapped room ID for this room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND", "errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found." "error": "Room alias #monkeys:example.org not found."
} }
schema:
"$ref": "definitions/errors/error.yaml"
tags: tags:
- Room directory - Room directory
"/rooms/{roomId}/aliases": "/rooms/{roomId}/aliases":
@ -212,29 +227,22 @@ paths:
Clients are recommended not to display this list of aliases prominently 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` as they are not curated, unlike those listed in the `m.room.canonical_alias`
state event. state event.
operationId: getLocalAliases operationId: getLocalAliases
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room ID to find local aliases of. description: The room ID to find local aliases of.
required: true required: true
x-example: "!abc123:example.org" example: "!abc123:example.org"
schema:
type: string
responses: responses:
200: "200":
description: |- description: The list of local aliases for the room.
The list of local aliases for the room. content:
examples: application/json:
application/json: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
schema: schema:
type: object type: object
properties: properties:
@ -243,28 +251,62 @@ paths:
description: The server's local aliases on the room. Can be empty. description: The server's local aliases on the room. Can be empty.
items: items:
type: string type: string
required: ['aliases'] required:
400: - aliases
description: The given `roomAlias` is not a valid room alias.
examples: examples:
application/json: { response:
value: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
"400":
description: The given `roomAlias` is not a valid room alias.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM", "errcode": "M_INVALID_PARAM",
"error": "Room alias invalid" "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: schema:
"$ref": "definitions/errors/error.yaml" $ref: definitions/errors/error.yaml
403:
description: The user is not permitted to retrieve the list of local aliases for the room.
examples: examples:
application/json: { response:
value: {
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "You are not a member of the room." "error": "You are not a member of the room."
} }
schema: "429":
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Room directory - Room directory
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Event Context API" title: Matrix Client-Server Event Context API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/rooms/{roomId}/context/{eventId}": "/rooms/{roomId}/context/{eventId}":
get: get:
@ -42,29 +31,31 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room to get events from. description: The room to get events from.
required: true required: true
x-example: "!636q39766251:example.com" example: "!636q39766251:example.com"
- in: path schema:
type: string type: string
- in: path
name: eventId name: eventId
description: The event to get context around. description: The event to get context around.
required: true required: true
x-example: "$f3h4d129462ha:example.com" example: $f3h4d129462ha:example.com
schema:
type: string
- in: query - in: query
type: integer
name: limit name: limit
description: |- description: |-
The maximum number of context events to return. The limit applies The maximum number of context events to return. The limit applies
to the sum of the `events_before` and `events_after` arrays. The to the sum of the `events_before` and `events_after` arrays. The
requested event ID is always returned in `event` even if `limit` is requested event ID is always returned in `event` even if `limit` is
0. Defaults to 10. 0. Defaults to 10.
x-example: 3 example: 3
schema:
type: integer
- in: query - in: query
name: filter name: filter
type: string
description: |- description: |-
A JSON `RoomEventFilter` to filter the returned events with. The A JSON `RoomEventFilter` to filter the returned events with. The
filter is only applied to `events_before`, `events_after`, and filter is only applied to `events_before`, `events_after`, and
@ -73,49 +64,50 @@ paths:
homeserver prefers. homeserver prefers.
See [Filtering](/client-server-api/#filtering) for more information. See [Filtering](/client-server-api/#filtering) for more information.
x-example: "66696p746572" example: 66696p746572
schema:
type: string
responses: responses:
200: "200":
description: The events and state surrounding the requested event. description: The events and state surrounding the requested event.
content:
application/json:
schema: schema:
type: object type: object
description: The events and state surrounding the requested event. description: The events and state surrounding the requested event.
properties: properties:
start: start:
type: string type: string
description: |- description: A token that can be used to paginate backwards with.
A token that can be used to paginate backwards with.
end: end:
type: string type: string
description: |- description: A token that can be used to paginate forwards with.
A token that can be used to paginate forwards with.
events_before: events_before:
type: array type: array
description: |- description: |-
A list of room events that happened just before the A list of room events that happened just before the
requested event, in reverse-chronological order. requested event, in reverse-chronological order.
items: items:
$ref: "definitions/client_event.yaml" $ref: definitions/client_event.yaml
event: event:
description: |- description: Details of the requested event.
Details of the requested event.
allOf: allOf:
- $ref: "definitions/client_event.yaml" - $ref: definitions/client_event.yaml
events_after: events_after:
type: array type: array
description: |- description: |-
A list of room events that happened just after the A list of room events that happened just after the
requested event, in chronological order. requested event, in chronological order.
items: items:
$ref: "definitions/client_event.yaml" $ref: definitions/client_event.yaml
state: state:
type: array type: array
description: |- description: The state of the room at the last event returned.
The state of the room at the last event returned.
items: items:
$ref: "definitions/client_event.yaml" $ref: definitions/client_event.yaml
examples: examples:
application/json: { response:
value: {
"end": "t29-57_2_0_2", "end": "t29-57_2_0_2",
"events_after": [ "events_after": [
{ {
@ -148,3 +140,18 @@ paths:
} }
tags: tags:
- Room participation - Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,20 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server filter API" title: Matrix Client-Server filter API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/user/{userId}/filter": "/user/{userId}/filter":
post: post:
@ -38,49 +28,77 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: userId name: userId
required: true required: true
description: description: The id of the user uploading the filter. The access token must be
The id of the user uploading the filter. The access token must be
authorized to make requests for this user id. authorized to make requests for this user id.
x-example: "@alice:example.com" example: "@alice:example.com"
- in: body schema:
name: filter type: string
required: true requestBody:
description: The filter to upload. content:
application/json:
schema: schema:
type: object type: object
allOf: allOf:
- $ref: "definitions/sync_filter.yaml" - $ref: definitions/sync_filter.yaml
example: { example: {
"room": { "room": {
"state": { "state": {
"types": ["m.room.*"], "types": [
"not_rooms": ["!726s6s6q:example.com"] "m.room.*"
],
"not_rooms": [
"!726s6s6q:example.com"
]
}, },
"timeline": { "timeline": {
"limit": 10, "limit": 10,
"types": ["m.room.message"], "types": [
"not_rooms": ["!726s6s6q:example.com"], "m.room.message"
"not_senders": ["@spam:example.com"] ],
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
]
}, },
"ephemeral": { "ephemeral": {
"types": ["m.receipt", "m.typing"], "types": [
"not_rooms": ["!726s6s6q:example.com"], "m.receipt",
"not_senders": ["@spam:example.com"] "m.typing"
],
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
]
} }
}, },
"presence": { "presence": {
"types": ["m.presence"], "types": [
"not_senders": ["@alice:example.com"] "m.presence"
],
"not_senders": [
"@alice:example.com"
]
}, },
"event_format": "client", "event_format": "client",
"event_fields": ["type", "content", "sender"] "event_fields": [
"type",
"content",
"sender"
]
} }
description: The filter to upload.
required: true
responses: responses:
200: "200":
description: The filter was created. description: The filter was created.
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -91,8 +109,9 @@ paths:
with a `{` as this character is used to determine with a `{` as this character is used to determine
if the filter provided is inline JSON or a previously if the filter provided is inline JSON or a previously
declared filter by homeservers on some APIs. declared filter by homeservers on some APIs.
example: "66696p746572" example: 66696p746572
required: ['filter_id'] required:
- filter_id
tags: tags:
- Room participation - Room participation
"/user/{userId}/filter/{filterId}": "/user/{userId}/filter/{filterId}":
@ -104,53 +123,95 @@ paths:
parameters: parameters:
- in: path - in: path
name: userId name: userId
type: string description: The user ID to download a filter for.
description: |-
The user ID to download a filter for.
x-example: "@alice:example.com"
required: true required: true
example: "@alice:example.com"
schema:
type: string
- in: path - in: path
name: filterId name: filterId
type: string description: The filter ID to download.
description: |-
The filter ID to download.
x-example: "66696p746572"
required: true required: true
example: 66696p746572
schema:
type: string
responses: responses:
200: "200":
description: |- description: The filter definition.
The filter definition. content:
examples: application/json:
application/json: {
"room": {
"state": {
"types": ["m.room.*"],
"not_rooms": ["!726s6s6q:example.com"]
},
"timeline": {
"limit": 10,
"types": ["m.room.message"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
},
"ephemeral": {
"types": ["m.receipt", "m.typing"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
}
},
"presence": {
"types": ["m.presence"],
"not_senders": ["@alice:example.com"]
},
"event_format": "client",
"event_fields": ["type", "content", "sender"]
}
schema: schema:
type: object type: object
allOf: allOf:
- $ref: "definitions/sync_filter.yaml" - $ref: definitions/sync_filter.yaml
404: examples:
description: "Unknown filter." 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: tags:
- Room participation - Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Room Joining API" title: Matrix Client-Server Room Joining API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
# With an extra " " to disambiguate from the 3pid invite endpoint # With an extra " " to disambiguate from the 3pid invite endpoint
# The extra space makes it sort first for what I'm sure is a good reason. # The extra space makes it sort first for what I'm sure is a good reason.
@ -47,20 +36,20 @@ paths:
If the user was invited to the room, the homeserver will append a If the user was invited to the room, the homeserver will append a
`m.room.member` event to the room. `m.room.member` event to the room.
operationId: inviteUser operationId: inviteUser
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) to which to invite the user. description: The room identifier (not alias) to which to invite the user.
required: true required: true
x-example: "!d41d8cd:matrix.org" example: "!d41d8cd:matrix.org"
- in: body schema:
name: body type: string
required: true requestBody:
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
@ -77,16 +66,21 @@ paths:
description: |- description: |-
Optional reason to be included as the `reason` on the subsequent Optional reason to be included as the `reason` on the subsequent
membership event. membership event.
required: ["user_id"] required:
- user_id
required: true
responses: responses:
200: "200":
description: The user has been invited to join the room, or was already invited to the room. description: The user has been invited to join the room, or was already invited
examples: to the room.
application/json: { content:
} application/json:
schema: schema:
type: object type: object
400: examples:
response:
value: {}
"400":
description: |- description: |-
The request is invalid. A meaningful `errcode` and 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 - One or more users being invited to the room are residents of a
homeserver which does not support the requested room version. The homeserver which does not support the requested room version. The
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/error.yaml" $ref: definitions/errors/error.yaml
403: "403":
description: |- description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
@ -108,14 +104,36 @@ paths:
- The invitee is already a member of the room. - The invitee is already a member of the room.
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} value: {
schema: "errcode": "M_FORBIDDEN",
"$ref": "definitions/errors/error.yaml" "error": "@cheeky_monkey:matrix.org is banned from the room"
429: }
"429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Room membership - Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Room Inviting API" title: Matrix Client-Server Room Inviting API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/rooms/{roomId}/join": "/rooms/{roomId}/join":
post: post:
@ -47,20 +36,21 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) to join. description: The room identifier (not alias) to join.
required: true required: true
x-example: "!d41d8cd:matrix.org" example: "!d41d8cd:matrix.org"
- in: body schema:
name: body type: string
required: true requestBody:
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
third_party_signed: third_party_signed:
allOf: allOf:
- $ref: "definitions/third_party_signed.yaml" - $ref: definitions/third_party_signed.yaml
description: |- description: |-
If supplied, the homeserver must verify that it matches a pending If supplied, the homeserver must verify that it matches a pending
`m.room.third_party_invite` event in the room, and perform `m.room.third_party_invite` event in the room, and perform
@ -71,24 +61,30 @@ paths:
description: |- description: |-
Optional reason to be included as the `reason` on the subsequent Optional reason to be included as the `reason` on the subsequent
membership event. membership event.
example: "Looking for support" example: Looking for support
required: true
responses: responses:
200: "200":
description: |- description: |-
The room has been joined. The room has been joined.
The joined room ID must be returned in the `room_id` field. The joined room ID must be returned in the `room_id` field.
examples: content:
application/json: { application/json:
"room_id": "!d41d8cd:matrix.org"}
schema: schema:
type: object type: object
properties: properties:
room_id: room_id:
type: string type: string
description: The joined room ID. description: The joined room ID.
required: ["room_id"] required:
403: - room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"403":
description: |- description: |-
You do not have permission to join the room. A meaningful `errcode` You do not have permission to join the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are: 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 room is invite-only and the user was not invited.
- The user has been banned from the room. - The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions. - The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} value: {
schema: "errcode": "M_FORBIDDEN",
"$ref": "definitions/errors/error.yaml" "error": "You are not invited to this room."
429: }
"429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Room membership - Room membership
"/join/{roomIdOrAlias}": "/join/{roomIdOrAlias}":
@ -126,29 +129,33 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomIdOrAlias name: roomIdOrAlias
description: The room identifier or alias to join. description: The room identifier or alias to join.
required: true required: true
x-example: "#monkeys:matrix.org" example: "#monkeys:matrix.org"
- in: query schema:
type: array
items:
type: string type: string
- in: query
name: server_name name: server_name
description: |- description: |-
The servers to attempt to join the room through. One of the servers The servers to attempt to join the room through. One of the servers
must be participating in the room. must be participating in the room.
x-example: ["matrix.org", "elsewhere.ca"] example:
- in: body - matrix.org
name: body - elsewhere.ca
required: true schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema: schema:
type: object type: object
properties: properties:
third_party_signed: third_party_signed:
allOf: allOf:
- $ref: "definitions/third_party_signed.yaml" - $ref: definitions/third_party_signed.yaml
description: |- description: |-
If a `third_party_signed` was supplied, the homeserver must verify If a `third_party_signed` was supplied, the homeserver must verify
that it matches a pending `m.room.third_party_invite` event in the that it matches a pending `m.room.third_party_invite` event in the
@ -159,24 +166,30 @@ paths:
description: |- description: |-
Optional reason to be included as the `reason` on the subsequent Optional reason to be included as the `reason` on the subsequent
membership event. membership event.
example: "Looking for support" example: Looking for support
required: true
responses: responses:
200: "200":
description: |- description: |-
The room has been joined. The room has been joined.
The joined room ID must be returned in the `room_id` field. The joined room ID must be returned in the `room_id` field.
examples: content:
application/json: { application/json:
"room_id": "!d41d8cd:matrix.org"}
schema: schema:
type: object type: object
properties: properties:
room_id: room_id:
type: string type: string
description: The joined room ID. description: The joined room ID.
required: ["room_id"] required:
403: - room_id
examples:
response:
value: {
"room_id": "!d41d8cd:matrix.org"
}
"403":
description: |- description: |-
You do not have permission to join the room. A meaningful `errcode` You do not have permission to join the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are: 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 room is invite-only and the user was not invited.
- The user has been banned from the room. - The user has been banned from the room.
- The room is restricted and the user failed to satisfy any of the conditions. - The room is restricted and the user failed to satisfy any of the conditions.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} value: {
schema: "errcode": "M_FORBIDDEN",
"$ref": "definitions/errors/error.yaml" "error": "You are not invited to this room."
429: }
"429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Room membership - Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

File diff suppressed because it is too large Load diff

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

@ -13,36 +13,21 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Client Config API" title: Matrix Client-Server Client Config API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/keys/upload": /keys/upload:
post: post:
summary: Upload end-to-end encryption keys. summary: Upload end-to-end encryption keys.
description: |- description: Publishes end-to-end encryption keys for the device.
Publishes end-to-end encryption keys for the device.
operationId: uploadKeys operationId: uploadKeys
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: keys application/json:
description: |-
The keys to be published
required: true
schema: schema:
type: object type: object
properties: properties:
@ -66,25 +51,18 @@ paths:
by the [key algorithm](/client-server-api/#key-algorithms). by the [key algorithm](/client-server-api/#key-algorithms).
May be absent if no new one-time keys are required. May be absent if no new one-time keys are required.
example: { example:
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", curve25519:AAAAAQ: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8
"signed_curve25519:AAAAHg": { signed_curve25519:AAAAHg:
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
"signatures": { signatures:
"@alice:example.com": { "@alice:example.com":
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
} signed_curve25519:AAAAHQ:
} key: j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw
}, signatures:
"signed_curve25519:AAAAHQ": { "@alice:example.com":
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
}
}
fallback_keys: fallback_keys:
x-addedInMatrixVersion: "1.2" x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml" # $ref: "definitions/one_time_keys.yaml"
@ -105,22 +83,21 @@ paths:
be included to denote that the key is a fallback key. be included to denote that the key is a fallback key.
May be absent if a new fallback key is not required. May be absent if a new fallback key is not required.
example: { example:
"curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8
"signed_curve25519:AAAAGj": { signed_curve25519:AAAAGj:
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
"fallback": true, fallback: true
"signatures": { signatures:
"@alice:example.com": { "@alice:example.com":
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
} description: The keys to be published
} required: true
}
}
responses: responses:
200: "200":
description: description: The provided keys were successfully uploaded.
The provided keys were successfully uploaded. content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -138,23 +115,18 @@ paths:
signed_curve25519: 20 signed_curve25519: 20
required: required:
- one_time_key_counts - one_time_key_counts
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/query": /keys/query:
post: post:
summary: Download device identity keys. summary: Download device identity keys.
description: |- description: Returns the current devices and identity keys for the given users.
Returns the current devices and identity keys for the given users.
operationId: queryKeys operationId: queryKeys
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: query application/json:
description: |-
Query defining the keys to be downloaded
required: true
schema: schema:
type: object type: object
properties: properties:
@ -174,16 +146,18 @@ paths:
type: array type: array
items: items:
type: string type: string
description: "device ID" description: device ID
example: example:
"@alice:example.com": [] "@alice:example.com": []
required: required:
- device_keys - device_keys
description: Query defining the keys to be downloaded
required: true
responses: responses:
200: "200":
description: description: The device information
The device information content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -225,30 +199,23 @@ paths:
properties: properties:
device_display_name: device_display_name:
type: string type: string
description: description: The display name which the user set on the device.
The display name which the user set on the device.
example: example:
"@alice:example.com": "@alice:example.com":
JLAFKJWSCS: { JLAFKJWSCS:
"user_id": "@alice:example.com", user_id: "@alice:example.com"
"device_id": "JLAFKJWSCS", device_id: JLAFKJWSCS
"algorithms": [ algorithms:
"m.olm.v1.curve25519-aes-sha2", - m.olm.v1.curve25519-aes-sha2
"m.megolm.v1.aes-sha2" - m.megolm.v1.aes-sha2
], keys:
"keys": { curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" signatures:
}, "@alice:example.com":
"signatures": { ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA
"@alice:example.com": { unsigned:
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" device_display_name: Alice's mobile phone
}
},
"unsigned": {
"device_display_name": "Alice's mobile phone"
}
}
master_keys: master_keys:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
@ -262,15 +229,13 @@ paths:
additionalProperties: additionalProperties:
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
example: { example:
"@alice:example.com": { "@alice:example.com":
"user_id": "@alice:example.com", user_id: "@alice:example.com"
"usage": ["master"], usage:
"keys": { - master
"ed25519:base64+master+public+key": "base64+master+public+key", keys:
} ed25519:base64+master+public+key: base64+master+public+key
}
}
self_signing_keys: self_signing_keys:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
@ -282,20 +247,16 @@ paths:
additionalProperties: additionalProperties:
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
example: { example:
"@alice:example.com": { "@alice:example.com":
"user_id": "@alice:example.com", user_id: "@alice:example.com"
"usage": ["self_signing"], usage:
"keys": { - self_signing
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", keys:
}, ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key
"signatures": { signatures:
"@alice:example.com": { "@alice:example.com":
"ed25519:base64+master+public+key": "signature+of+self+signing+key" ed25519:base64+master+public+key: signature+of+self+signing+key
}
}
}
}
user_signing_keys: user_signing_keys:
type: object type: object
description: |- description: |-
@ -307,36 +268,28 @@ paths:
additionalProperties: additionalProperties:
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
example: { example:
"@alice:example.com": { "@alice:example.com":
"user_id": "@alice:example.com", user_id: "@alice:example.com"
"usage": ["user_signing"], usage:
"keys": { - user_signing
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", keys:
}, ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key
"signatures": { signatures:
"@alice:example.com": { "@alice:example.com":
"ed25519:base64+master+public+key": "signature+of+user+signing+key" ed25519:base64+master+public+key: signature+of+user+signing+key
}
}
}
}
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/claim": /keys/claim:
post: post:
summary: Claim one-time encryption keys. summary: Claim one-time encryption keys.
description: |- description: Claims one-time keys for use in pre-key messages.
Claims one-time keys for use in pre-key messages.
operationId: claimKeys operationId: claimKeys
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: query application/json:
description: |-
Query defining the keys to be claimed
required: true
schema: schema:
type: object type: object
properties: properties:
@ -356,16 +309,19 @@ paths:
additionalProperties: additionalProperties:
type: string type: string
description: algorithm description: algorithm
example: "signed_curve25519" example: signed_curve25519
example: { example:
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } "@alice:example.com":
} JLAFKJWSCS: signed_curve25519
required: required:
- one_time_keys - one_time_keys
description: Query defining the keys to be claimed
required: true
responses: responses:
200: "200":
description: description: The claimed keys.
The claimed keys. content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -403,24 +359,19 @@ paths:
# See also one_time_key parameter for /keys/upload above. # See also one_time_key parameter for /keys/upload above.
type: object type: object
title: OneTimeKeys title: OneTimeKeys
example: { example:
"@alice:example.com": { "@alice:example.com":
"JLAFKJWSCS": { JLAFKJWSCS:
"signed_curve25519:AAAAHg": { signed_curve25519:AAAAHg:
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
"signatures": { signatures:
"@alice:example.com": { "@alice:example.com":
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
} required:
} - one_time_keys
}
}
}
}
required: ['one_time_keys']
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/changes": /keys/changes:
get: get:
summary: Query users with recent device key updates. summary: Query users with recent device key updates.
description: |- description: |-
@ -439,7 +390,6 @@ paths:
parameters: parameters:
- in: query - in: query
name: from name: from
type: string
description: |- description: |-
The desired start point of the list. Should be the `next_batch` field 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 from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not
@ -447,21 +397,25 @@ paths:
existing devices with identity keys since then, will be excluded existing devices with identity keys since then, will be excluded
from the results. from the results.
required: true required: true
x-example: "s72594_4483_1934" example: s72594_4483_1934
schema:
type: string
- in: query - in: query
name: to name: to
type: string
description: |- description: |-
The desired end point of the list. Should be the `next_batch` 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 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 such call. This may be used by the server as a hint to check its
caches are up to date. caches are up to date.
required: true required: true
x-example: "s75689_5632_2435" example: s75689_5632_2435
schema:
type: string
responses: responses:
200: "200":
description: description: The list of users who updated their devices.
The list of users who updated their devices. content:
application/json:
schema: schema:
type: object type: object
properties: properties:
@ -472,7 +426,9 @@ paths:
description: |- description: |-
The Matrix User IDs of all users who updated their device The Matrix User IDs of all users who updated their device
identity keys. identity keys.
example: ["@alice:example.com", "@bob:example.org"] example:
- "@alice:example.com"
- "@bob:example.org"
left: left:
type: array type: array
items: items:
@ -481,6 +437,23 @@ paths:
The Matrix User IDs of all users who may have left all The Matrix User IDs of all users who may have left all
the end-to-end encrypted rooms they previously shared the end-to-end encrypted rooms they previously shared
with the user. with the user.
example: ["@clara:example.com", "@doug:example.org"] example:
- "@clara:example.com"
- "@doug:example.org"
tags: tags:
- End-to-end encryption - End-to-end encryption
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

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

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

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

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

@ -11,48 +11,54 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Room Listing API" title: Matrix Client-Server Room Listing API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/joined_rooms": /joined_rooms:
get: get:
summary: Lists the user's current rooms. summary: Lists the user's current rooms.
description: |- description: This API returns a list of the user's current rooms.
This API returns a list of the user's current rooms.
operationId: getJoinedRooms operationId: getJoinedRooms
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: A list of the rooms the user is in. description: A list of the rooms the user is in.
content:
application/json:
schema: schema:
type: object type: object
required: ["joined_rooms"] required:
- joined_rooms
properties: properties:
joined_rooms: joined_rooms:
type: array type: array
description: |- description: The ID of each room in which the user has `joined` membership.
The ID of each room in which the user has `joined` membership.
items: items:
type: string type: string
examples: examples:
application/json: { response:
value: {
"joined_rooms": [ "joined_rooms": [
"!foo:example.com" "!foo:example.com"
] ]
} }
tags: tags:
- Room membership - Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

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

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

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

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Registration and Login API" title: Matrix Client-Server Registration and Login API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/logout": /logout:
post: post:
summary: Invalidates a user access token summary: Invalidates a user access token
description: |- description: |-
@ -38,14 +27,16 @@ paths:
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The access token used in the request was successfully invalidated. description: The access token used in the request was successfully invalidated.
content:
application/json:
schema: schema:
type: object type: object
properties: {} properties: {}
tags: tags:
- Session management - Session management
"/logout/all": /logout/all:
post: post:
summary: Invalidates all access tokens for a user summary: Invalidates all access tokens for a user
description: |- description: |-
@ -64,10 +55,27 @@ paths:
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The user's access tokens were successfully invalidated. description: The user's access tokens were successfully invalidated.
content:
application/json:
schema: schema:
type: object type: object
properties: {} properties: {}
tags: 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
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Room Membership API for third-party identifiers" title: Matrix Client-Server Room Membership API for third-party identifiers
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/rooms/{roomId}/invite": "/rooms/{roomId}/invite":
post: post:
@ -71,20 +60,20 @@ paths:
If a token is requested from the identity server, the homeserver will If a token is requested from the identity server, the homeserver will
append a `m.room.third_party_invite` event to the room. append a `m.room.third_party_invite` event to the room.
operationId: inviteBy3PID operationId: inviteBy3PID
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) to which to invite the user. description: The room identifier (not alias) to which to invite the user.
required: true required: true
x-example: "!d41d8cd:matrix.org" example: "!d41d8cd:matrix.org"
- in: body schema:
name: body type: string
required: true requestBody:
content:
application/json:
schema: schema:
type: object type: object
example: { example: {
@ -96,7 +85,8 @@ paths:
properties: properties:
id_server: id_server:
type: string type: string
description: The hostname+port of the identity server which should be used for third-party identifier lookups. description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token: id_access_token:
type: string type: string
description: |- description: |-
@ -111,16 +101,23 @@ paths:
address: address:
type: string type: string
description: The invitee's third-party identifier. description: The invitee's third-party identifier.
required: ["id_server", "id_access_token", "medium", "address"] required:
- id_server
- id_access_token
- medium
- address
required: true
responses: responses:
200: "200":
description: The user has been invited to join the room. description: The user has been invited to join the room.
examples: content:
application/json: { application/json:
}
schema: schema:
type: object type: object
403: examples:
response:
value: {}
"403":
description: |- description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
@ -128,14 +125,36 @@ paths:
- The invitee is already a member of the room. - The invitee is already a member of the room.
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples: examples:
application/json: { response:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} value: {
schema: "errcode": "M_FORBIDDEN",
"$ref": "definitions/errors/error.yaml" "error": "@cheeky_monkey:matrix.org is banned from the room"
429: }
"429":
description: This request was rate-limited. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- Room membership - Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

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

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

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

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

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

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

@ -11,19 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Versions API" title: Matrix Client-Server Versions API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client
produces:
- application/json
paths: paths:
"/versions": /versions:
get: get:
summary: Gets the versions of the specification supported by the server. summary: Gets the versions of the specification supported by the server.
description: |- description: |-
@ -47,15 +40,10 @@ paths:
features in their stable releases. features in their stable releases.
operationId: getVersions operationId: getVersions
responses: responses:
200: "200":
description: The versions supported by the server. description: The versions supported by the server.
examples: content:
application/json: { application/json:
"versions": ["r0.0.1", "v1.1"],
"unstable_features": {
"org.example.my_feature": true
}
}
schema: schema:
type: object type: object
properties: properties:
@ -74,6 +62,30 @@ paths:
additionalProperties: additionalProperties:
type: boolean type: boolean
description: Whether or not the namespaced feature is supported. description: Whether or not the namespaced feature is supported.
required: ['versions'] required:
- versions
examples:
response:
value: {
"versions": [
"r0.0.1",
"v1.1"
],
"unstable_features": {
"org.example.my_feature": true
}
}
tags: tags:
- Server administration - Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Voice over IP API" title: Matrix Client-Server Voice over IP API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths: paths:
"/voip/turnServer": /voip/turnServer:
get: get:
summary: Obtain TURN server credentials. summary: Obtain TURN server credentials.
description: |- description: |-
@ -37,30 +26,19 @@ paths:
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The TURN server credentials. description: The TURN server credentials.
examples: content:
application/json: { 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: schema:
type: object type: object
properties: properties:
username: username:
type: string type: string
description: |- description: The username to use.
The username to use.
password: password:
type: string type: string
description: |- description: The password to use.
The password to use.
uris: uris:
type: array type: array
items: items:
@ -69,10 +47,43 @@ paths:
ttl: ttl:
type: integer type: integer
description: The time-to-live in seconds description: The time-to-live in seconds
required: ["username", "password", "uris", "ttl"] required:
429: - 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. description: This request was rate-limited.
content:
application/json:
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" $ref: definitions/errors/rate_limited.yaml
tags: tags:
- VOIP - VOIP
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,18 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Client-Server Server Discovery API" title: Matrix Client-Server Server Discovery API
version: "1.0.0" version: 1.0.0
host: localhost:8008
schemes:
- https
basePath: /.well-known
produces:
- application/json
paths: paths:
"/matrix/client": /matrix/client:
get: get:
summary: Gets Matrix server discovery information about the domain. summary: Gets Matrix server discovery information about the domain.
description: |- description: |-
@ -36,11 +30,25 @@ paths:
but by another webserver, to be used for discovering the homeserver URL. but by another webserver, to be used for discovering the homeserver URL.
operationId: getWellknown operationId: getWellknown
responses: responses:
200: "200":
description: Server discovery information. description: Server discovery information.
content:
application/json:
schema: schema:
"$ref": "definitions/wellknown/full.yaml" $ref: definitions/wellknown/full.yaml
404: "404":
description: No server discovery information available. description: No server discovery information available.
tags: tags:
- Server administration - Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /.well-known

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -13,19 +13,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
openapi: 3.1.0
swagger: "2.0"
info: info:
title: "Matrix Identity Service Ping API" title: Matrix Identity Service Ping API
version: "2.0.0" version: 2.0.0
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
paths: paths:
"/v2": /v2:
get: get:
summary: Checks that an identity server is available at this API endpoint. summary: Checks that an identity server is available at this API endpoint.
description: |- description: |-
@ -38,9 +31,24 @@ paths:
by entities acting as a client for the identity server. by entities acting as a client for the identity server.
operationId: pingV2 operationId: pingV2
responses: responses:
200: "200":
description: An identity server is ready to serve requests. description: An identity server is ready to serve requests.
examples: content:
application/json: {} application/json:
schema: schema:
type: object type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

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

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

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

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

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

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

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

@ -11,18 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
swagger: '2.0' openapi: 3.1.0
info: info:
title: "Matrix Identity Service Versions API" title: Matrix Identity Service Versions API
version: "1.0.0" version: 1.0.0
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
paths: paths:
"/versions": /versions:
get: get:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
summary: Gets the versions of the specification supported by the server. summary: Gets the versions of the specification supported by the server.
@ -36,12 +30,10 @@ paths:
All supported versions, including patch versions, are reported by the server. All supported versions, including patch versions, are reported by the server.
operationId: getVersions operationId: getVersions
responses: responses:
200: "200":
description: The versions supported by the server. description: The versions supported by the server.
examples: content:
application/json: { application/json:
"versions": ["r0.2.0", "r0.2.1", "v1.1"]
}
schema: schema:
type: object type: object
properties: properties:
@ -51,4 +43,26 @@ paths:
items: items:
type: string type: string
description: The supported versions. description: The supported versions.
required: ['versions'] required:
- versions
examples:
response:
value: {
"versions": [
"r0.2.0",
"r0.2.1",
"v1.1"
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -11,19 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
openapi: 3.1.0
swagger: '2.0'
info: info:
title: "Matrix Federation Key Exchange API" title: Matrix Federation Key Exchange API
version: "1.0.0" version: 1.0.0
host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
produces:
- application/json
paths: paths:
"/server": /server:
get: get:
summary: Get the homeserver's public key(s) summary: Get the homeserver's public key(s)
description: |- description: |-
@ -44,7 +37,21 @@ paths:
checked. checked.
operationId: getServerKey operationId: getServerKey
responses: responses:
200: "200":
description: The homeserver's keys description: The homeserver's keys
content:
application/json:
schema: schema:
$ref: "definitions/keys.yaml" $ref: definitions/keys.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/key/v2

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

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

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

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

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

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

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

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

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

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

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

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