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

Upgrade Swagger data to OpenAPI 3.1 (#1310)

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

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

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

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

@ -11,21 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,25 +30,43 @@ 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: { "transaction_id": "mautrix-go_1683636478256400935_123"
"transaction_id": "mautrix-go_1683636478256400935_123" }
} properties:
properties: transaction_id:
transaction_id: type: string
type: string 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

395
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
responses:
200:
description: The protocol was found and metadata returned.
schema: schema:
$ref: definitions/protocol.yaml type: string
401: responses:
"200":
description: The protocol was found and metadata returned.
content:
application/json:
schema:
$ref: definitions/protocol.yaml
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"404":
description: No protocol was found with the given path. description: No protocol was found with the given path.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/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.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema: schema:
$ref: definitions/user_batch.yaml type: string
401: responses:
"200":
description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"404":
description: No users were found with the given parameters. description: No users were found with the given parameters.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/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.
responses:
200:
description: At least one portal room was found.
schema: schema:
$ref: definitions/location_batch.yaml type: string
401: responses:
"200":
description: At least one portal room was found.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters. description: No mappings were found with the given parameters.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
"/thirdparty/location": value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/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.
responses:
200:
description: |-
All found third-party locations.
schema: schema:
$ref: definitions/location_batch.yaml type: string
401: responses:
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters. description: No mappings were found with the given parameters.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
"/thirdparty/user": value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/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.
responses:
200:
description: |-
An array of third-party users.
schema: schema:
$ref: definitions/user_batch.yaml type: string
401: responses:
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" 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.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
examples: content:
application/json: { application/json:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
403: value: {
description: |- "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
The credentials supplied by the homeserver were rejected. }
examples: "403":
application/json: { description: The credentials supplied by the homeserver were rejected.
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" 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_FORBIDDEN"
}
"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:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
$ref: ../client-server/definitions/errors/error.yaml response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,19 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
name: body
description: Transaction information
schema: schema:
type: object type: string
example: { requestBody:
"events": [ content:
{"$ref": "../../event-schemas/examples/m.room.member.yaml"}, application/json:
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} schema:
] type: object
} example: {
properties: "events": [
events: {
type: array "$ref": "../../event-schemas/examples/m.room.member.yaml"
description: |- },
A list of events, formatted as per the Client-Server API. {
items: "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
$ref: "../client-server/definitions/client_event.yaml" }
required: ["events"] ]
}
properties:
events:
type: array
description: A list of events, formatted as per the Client-Server API.
items:
$ref: ../client-server/definitions/client_event.yaml
required:
- events
description: Transaction information
responses: 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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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"
schema:
type: string
- in: path - in: path
type: string
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
name: content
required: true
description: |-
The content of the account data.
schema: schema:
type: object type: string
example: { requestBody:
"custom_account_data_key": "custom_config_value"} content:
application/json:
schema:
type: object
example: {
"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 examples:
400: 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`.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_JSON", schema:
"error": "Content must be a JSON object." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
403: "errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "Cannot add account data for other users." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
405: "errcode": "M_FORBIDDEN",
examples: "error": "Cannot add account data for other users."
application/json: { }
"errcode": "M_BAD_JSON", "405":
"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`.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
tags: 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"
schema:
type: string
- in: path - in: path
type: string
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
responses:
200:
description:
The account data content for the given type.
schema: schema:
type: object type: string
example: { responses:
"custom_account_data_key": "custom_config_value"} "200":
403: description: The account data content for the given type.
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"
}
"403":
description: |- 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`.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "Cannot add account data for other users." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
404: "errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Account data not found." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
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"
schema:
type: string
- in: path - in: path
type: string
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:
type: string
- in: path - in: path
type: string
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
name: content
required: true
description: |-
The content of the account data.
schema: schema:
type: object type: string
example: { requestBody:
"custom_account_data_key": "custom_account_data_value"} content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"
}
description: The content of the account data.
required: true
responses: 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 examples:
400: 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`).
examples: content:
application/json: { application/json:
"errcode": "M_NOT_JSON", schema:
"error": "Content must be a JSON object." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
403: "errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "Cannot add account data for other users." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
405: "errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_BAD_JSON", schema:
"error": "Cannot set m.fully_read through this API." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
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"
schema:
type: string
- in: path - in: path
type: string
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:
type: string
- in: path - in: path
type: string
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
responses:
200:
description:
The account data content for the given type.
schema: schema:
type: object type: string
example: { responses:
"custom_account_data_key": "custom_config_value"} "200":
400: description: The account data content for the given type.
description: |- content:
The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`. application/json:
examples: schema:
application/json: { type: object
"errcode": "M_INVALID_PARAM", example: {
"error": "@notaroomid:example.org is not a valid room ID." "custom_account_data_key": "custom_config_value"
} }
403: "400":
description: "The given `roomID` is not a valid room ID. Errcode:
`M_INVALID_PARAM`."
content:
application/json:
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
"403":
description: |- 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`.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "Cannot add account data for other users." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
404: "errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Room account data not found." $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
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

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

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

@ -12,23 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,48 +33,56 @@ 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": [ schema:
{ type: object
"medium": "email", properties:
"address": "monkey@banana.island", threepids:
"validated_at": 1535176800000, type: array
"added_at": 1535336848756 items:
} type: object
] title: Third-party identifier
} properties:
schema: medium:
type: object type: string
properties: description: The medium of the third-party identifier.
threepids: enum:
type: array - email
items: - msisdn
type: object address:
title: Third-party identifier type: string
properties: description: The third-party identifier address.
medium: validated_at:
type: string type: integer
description: The medium of the third-party identifier. format: int64
enum: ["email", "msisdn"] description: |-
address: The timestamp, in milliseconds, when the identifier was
type: string validated by the identity server.
description: The third-party identifier address. added_at:
validated_at: type: integer
type: integer format: int64
format: int64 description: The timestamp, in milliseconds, when the homeserver associated the
description: |- third-party identifier with the user.
The timestamp, in milliseconds, when the identifier was required:
validated by the identity server. - medium
added_at: - address
type: integer - validated_at
format: int64 - added_at
description: examples:
The timestamp, in milliseconds, when the homeserver response:
associated the third-party identifier with the user. value: {
required: ['medium', 'address', 'validated_at', 'added_at'] "threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
tags: tags:
- Account management - Account management
post: post:
@ -105,36 +102,40 @@ 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: client_secret:
client_secret: type: string
type: string description: The client secret used in the session with the identity server.
description: The client secret used in the session with the identity server. id_server:
id_server: type: string
type: string 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. Servers
An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients
can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
and this specification version. 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:
required: ["client_secret", "id_server", "id_access_token", "sid"] - client_secret
required: ["three_pid_creds"] - id_server
example: { - id_access_token
- sid
required:
- three_pid_creds
example: {
"three_pid_creds": { "three_pid_creds": {
"id_server": "matrix.org", "id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString", "id_access_token": "abc123_OpaqueString",
@ -142,45 +143,52 @@ 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:
} type: object
schema: properties:
type: object submit_url:
properties: type: string
submit_url: format: uri
type: string description: |-
format: uri An optional field containing a URL where the client must
description: |- submit the validation token to, with identical parameters
An optional field containing a URL where the client must to the Identity Service API's `POST
submit the validation token to, with identical parameters /validate/email/submitToken` endpoint (without the requirement
to the Identity Service API's `POST for an access token). The homeserver must send this token to the
/validate/email/submitToken` endpoint (without the requirement user (if applicable), who should then be prompted to provide it
for an access token). The homeserver must send this token to the to the client.
user (if applicable), who should then be prompted to provide it
to the client.
If this field is not present, the client can assume that If this field is not present, the client can assume that
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: examples:
response:
value: {
"submit_url": "https://example.org/path/to/submitToken"
}
"403":
description: The credentials could not be verified with the identity server. description: The credentials could not be verified with the identity server.
examples: content:
application/json: { application/json:
"errcode": "M_THREEPID_AUTH_FAILED", schema:
"error": "The third-party credentials could not be verified by the identity server." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third-party credentials could not be verified by the identity server."
}
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,47 +202,55 @@ 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: auth:
auth: description: |-
description: |- 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:
required: ["client_secret", "sid"] - 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: {}
schema: "401":
"$ref": "definitions/auth_response.yaml" description: The homeserver requires additional authentication information.
429: content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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,47 +264,55 @@ 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: client_secret:
client_secret: type: string
type: string description: The client secret used in the session with the identity server.
description: The client secret used in the session with the identity server. id_server:
id_server: type: string
type: string description: The identity server to use.
description: The identity server to use. id_access_token:
id_access_token: type: string
type: string description: An access token previously registered with the identity server.
description: |- sid:
An access token previously registered with the identity server. type: string
sid: description: The session identifier given by the identity server.
type: string required:
description: The session identifier given by the identity server. - client_secret
required: ["client_secret", "id_server", "id_access_token", "sid"] - id_server
example: { - id_access_token
"id_server": "example.org", - sid
"id_access_token": "abc123_OpaqueString", example: {
"sid": "abc123987", "id_server": "example.org",
"client_secret": "d0nt-T3ll" "id_access_token": "abc123_OpaqueString",
} "sid": "abc123987",
"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.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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,59 +325,63 @@ 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: id_server:
id_server: type: string
type: string description: |-
description: |-
The identity server to unbind from. If not provided, the homeserver The identity server to unbind from. If not provided, the homeserver
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
address: - msisdn
type: string example: email
description: The third-party address being removed. address:
example: "example@example.org" type: string
required: ['medium', 'address'] description: The third-party address being removed.
example: example@example.org
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.
schema: content:
type: object application/json:
properties: schema:
id_server_unbind_result: type: object
type: string properties:
enum: id_server_unbind_result:
# XXX: I don't know why, but the order matters here so that "no-support" type: string
# doesn't become "no- support" by the renderer. enum:
- "no-support" - no-support
- "success" - 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
identity server has unbound the identifier whereas `no-support` identity server has unbound the identifier whereas `no-support`
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,60 +394,65 @@ 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: id_server:
id_server: type: string
type: string description: |-
description: |-
The identity server to unbind from. If not provided, the homeserver The identity server to unbind from. If not provided, the homeserver
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
address: - msisdn
type: string example: email
description: The third-party address being removed. address:
example: "example@example.org" type: string
required: ['medium', 'address'] description: The third-party address being removed.
example: example@example.org
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.
schema: content:
type: object application/json:
properties: schema:
id_server_unbind_result: type: object
type: string properties:
enum: id_server_unbind_result:
# XXX: I don't know why, but the order matters here so that "no-support" type: string
# doesn't become "no- support" by the renderer. enum:
- "no-support" - no-support
- "success" - 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.
schema: content:
$ref: "definitions/request_token_response.yaml" application/json:
403: schema:
description: |- $ref: definitions/request_token_response.yaml
The homeserver does not allow the third-party identifier as a "400":
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.
schema: content:
$ref: "definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: definitions/errors/error.yaml
"errcode": "M_THREEPID_IN_USE", examples:
"error": "Third-party identifier already in use" response:
} value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags: 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:
required: true schema:
schema: $ref: definitions/request_msisdn_validation.yaml
$ref: "definitions/request_msisdn_validation.yaml" required: true
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.
schema: content:
$ref: "definitions/request_token_response.yaml" application/json:
403: schema:
description: |- $ref: definitions/request_token_response.yaml
The homeserver does not allow the third-party identifier as a "400":
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.
schema: content:
$ref: "definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: definitions/errors/error.yaml
"errcode": "M_THREEPID_IN_USE", examples:
"error": "Third-party identifier already in use" response:
} value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags: 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

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

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

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

@ -11,28 +11,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
schema:
type: string
- in: path - in: path
type: string
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
name: body
required: true
schema: schema:
type: object type: string
properties: requestBody:
visibility: content:
type: string application/json:
enum: ["public", "private"] schema:
description: |- type: object
Whether the room should be visible (public) in the directory properties:
or not (private). visibility:
example: "public" type: string
required: ['visibility'] enum:
- public
- private
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: public
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.
schema: content:
type: object application/json:
examples: schema:
application/json: {} type: object
examples:
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

186
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,51 +30,60 @@ 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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Telling unfunny jokes", "reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org" "user_id": "@cheeky_monkey:matrix.org"
} }
properties: properties:
user_id: user_id:
type: string type: string
description: The fully qualified user ID of the user being banned. description: The fully qualified user ID of the user being banned.
reason: reason:
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 examples:
403: response:
value: {}
"403":
description: |- description: |-
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room. - The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room. - The banner's power level is insufficient to ban users from the room.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "You do not have a high enough power level to ban from this room." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags: tags:
- Room membership - Room membership
"/rooms/{roomId}/unban": "/rooms/{roomId}/unban":
@ -101,50 +99,74 @@ paths:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) from which the user should be unbanned. description: The room identifier (not alias) from which the user should be
required: true unbanned.
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true required: true
example: "!e42d8c:matrix.org"
schema: schema:
type: object type: string
example: { requestBody:
"user_id": "@cheeky_monkey:matrix.org", content:
"reason": "They've been banned long enough" application/json:
} schema:
properties: type: object
user_id: example: {
type: string "user_id": "@cheeky_monkey:matrix.org",
description: The fully qualified user ID of the user being unbanned. "reason": "They've been banned long enough"
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: {
} }
schema: properties:
type: object user_id:
403: type: string
description: The fully qualified user ID of the user being unbanned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required: true
responses:
"200":
description: The user has been unbanned from the room.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"403":
description: |- description: |-
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room. - The unbanner's power level is insufficient to unban users from the room.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "You do not have a high enough power level to unban from this room." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
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

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

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

File diff suppressed because it is too large Load diff

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

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

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,87 +27,93 @@ paths:
operationId: uploadCrossSigningKeys operationId: uploadCrossSigningKeys
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: keys application/json:
description: |- schema:
The keys to be published. type: object
required: true properties:
schema: master_key:
type: object description: Optional. The user\'s master key.
properties: allOf:
master_key: - $ref: definitions/cross_signing_key.yaml
description: |- self_signing_key:
Optional. The user\'s master key. description: |-
allOf: Optional. The user\'s self-signing key. Must be signed by
- $ref: definitions/cross_signing_key.yaml the accompanying master key, or by the user\'s most recently
self_signing_key: uploaded master key if no master key is included in the
description: |- request.
Optional. The user\'s self-signing key. Must be signed by allOf:
the accompanying master key, or by the user\'s most recently - $ref: definitions/cross_signing_key.yaml
uploaded master key if no master key is included in the user_signing_key:
request. description: |-
allOf: Optional. The user\'s user-signing key. Must be signed by
- $ref: definitions/cross_signing_key.yaml the accompanying master key, or by the user\'s most recently
user_signing_key: uploaded master key if no master key is included in the
description: |- request.
Optional. The user\'s user-signing key. Must be signed by allOf:
the accompanying master key, or by the user\'s most recently - $ref: definitions/cross_signing_key.yaml
uploaded master key if no master key is included in the auth:
request. description: |-
allOf: Additional authentication information for the
- $ref: definitions/cross_signing_key.yaml user-interactive authentication API.
auth: allOf:
description: |- - $ref: definitions/auth_data.yaml
Additional authentication information for the example: {
user-interactive authentication API. "auth": {
allOf: "type": "example.type.foo",
- $ref: "definitions/auth_data.yaml" "session": "xxxxx",
example: { "example_credential": "verypoorsharedsecret"
"auth": {
"type": "example.type.foo",
"session": "xxxxx",
"example_credential": "verypoorsharedsecret"
},
"master_key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
}
},
"self_signing_key": {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
}, },
"signatures": { "master_key": {
"@alice:example.com": { "user_id": "@alice:example.com",
"ed25519:base64+master+public+key": "signature+of+self+signing+key" "usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
} }
}
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
}, },
"signatures": { "self_signing_key": {
"@alice:example.com": { "user_id": "@alice:example.com",
"ed25519:base64+master+public+key": "signature+of+user+signing+key" "usage": [
"self_signing"
],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
}
}
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": [
"user_signing"
],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
}
} }
} }
} }
} description: The keys to be published.
required: true
responses: responses:
200: "200":
description: The provided keys were successfully uploaded. description: The provided keys were successfully uploaded.
schema: content:
type: object application/json:
example: {} schema:
400: type: object
example: {}
"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,25 +121,29 @@ 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.
schema: content:
type: object application/json:
example: { schema:
"errcode": "M_INVALID_SIGNATURE", type: object
"error": "Invalid signature" example: {
} "errcode": "M_INVALID_SIGNATURE",
403: "error": "Invalid signature"
}
"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.
schema: content:
type: object application/json:
example: { schema:
"errcode": "M_FORBIDDEN", type: object
"error": "Key ID in use" example: {
} "errcode": "M_FORBIDDEN",
"error": "Key ID in use"
}
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,91 +157,109 @@ paths:
operationId: uploadCrossSigningSignatures operationId: uploadCrossSigningSignatures
security: security:
- accessToken: [] - accessToken: []
parameters: requestBody:
- in: body content:
name: signatures application/json:
description: |- schema:
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
schema:
type: object
title: Signatures
additionalProperties:
type: object type: object
title: Signatures
additionalProperties: additionalProperties:
type: object type: object
example: { additionalProperties:
"@alice:example.com": { type: object
"HIJKLMN": { example: {
"user_id": "@alice:example.com", "@alice:example.com": {
"device_id": "HIJKLMN", "HIJKLMN": {
"algorithms": [ "user_id": "@alice:example.com",
"m.olm.v1.curve25519-aes-sha256", "device_id": "HIJKLMN",
"m.megolm.v1.aes-sha" "algorithms": [
], "m.olm.v1.curve25519-aes-sha256",
"keys": { "m.megolm.v1.aes-sha"
"curve25519:HIJKLMN": "base64+curve25519+key", ],
"ed25519:HIJKLMN": "base64+ed25519+key" "keys": {
"curve25519:HIJKLMN": "base64+curve25519+key",
"ed25519:HIJKLMN": "base64+ed25519+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
}
}
}, },
"signatures": { "base64+master+public+key": {
"@alice:example.com": { "user_id": "@alice:example.com",
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" "usage": [
"master"
],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:HIJKLMN": "base64+signature+of+master+key"
}
} }
} }
}, },
"base64+master+public+key": { "@bob:example.com": {
"user_id": "@alice:example.com", "bobs+base64+master+public+key": {
"usage": ["master"], "user_id": "@bob:example.com",
"keys": { "keys": {
"ed25519:base64+master+public+key": "base64+master+public+key" "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
}, },
"signatures": { "usage": [
"@alice:example.com": { "master"
"ed25519:HIJKLMN": "base64+signature+of+master+key" ],
} "signatures": {
} "@alice:example.com": {
} "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
}, }
"@bob:example.com": {
"bobs+base64+master+public+key": {
"user_id": "@bob:example.com",
"keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
},
"usage": ["master"],
"signatures": {
"@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
} }
} }
} }
} }
} description: |-
A map from user ID to key ID to signed JSON objects containing the
signatures to be published.
required: true
responses: responses:
200: "200":
description: The provided signatures were processed. description: The provided signatures were processed.
schema: content:
type: object application/json:
properties: schema:
failures:
type: object type: object
description: |- properties:
A map from user ID to key ID to an error for any signatures failures:
that failed. If a signature was invalid, the `errcode` will
be set to `M_INVALID_SIGNATURE`.
additionalProperties:
type: object
additionalProperties:
type: object type: object
title: Error description: |-
example: { A map from user ID to key ID to an error for any signatures
"@alice:example.com": { that failed. If a signature was invalid, the `errcode` will
"HIJKLMN": { be set to `M_INVALID_SIGNATURE`.
"errcode": "M_INVALID_SIGNATURE", additionalProperties:
"error": "Invalid signature" type: object
} additionalProperties:
} type: object
} title: Error
example:
"@alice:example.com":
HIJKLMN:
errcode: M_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.

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

@ -11,126 +11,124 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
schema: content:
type: object application/json:
properties: schema:
devices: type: object
type: array properties:
description: A list of all registered devices for this user. devices:
items: type: array
type: object description: A list of all registered devices for this user.
allOf: items:
- $ref: "definitions/client_device.yaml" type: object
examples: allOf:
application/json: { - $ref: definitions/client_device.yaml
"devices": [ examples:
{ response:
"device_id": "QBUAZIFURK", value: {
"display_name": "android", "devices": [
"last_seen_ip": "1.2.3.4", {
"last_seen_ts": 1474491775024 "device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
]
} }
]
}
tags: tags:
- Device management - Device management
"/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
responses:
200:
description: Device information
schema: schema:
type: object type: string
allOf: responses:
- $ref: "definitions/client_device.yaml" "200":
examples: description: Device information
application/json: { content:
"device_id": "QBUAZIFURK", application/json:
"display_name": "android", schema:
"last_seen_ip": "1.2.3.4", type: object
"last_seen_ts": 1474491775024 allOf:
} - $ref: definitions/client_device.yaml
404: examples:
response:
value: {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
"404":
description: The current user has no device with the given ID. 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
name: body
required: true
description: New information for the device.
schema: schema:
type: object type: string
properties: requestBody:
display_name: content:
type: string application/json:
description: |- schema:
The new display name for this device. If not given, the type: object
display name is unchanged. properties:
example: { "display_name": "My other phone" } display_name:
responses: type: string
200: description: |-
description: The device was successfully updated. The new display name for this device. If not given, the
examples: display name is unchanged.
application/json: { example: {
"display_name": "My other phone"
} }
schema: description: New information for the device.
type: object # empty json object required: true
404: responses:
"200":
description: The device was successfully updated.
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"404":
description: The current user has no device with the given ID. description: The current user has no device with the given ID.
tags: tags:
- Device management - Device management
@ -145,41 +143,46 @@ 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
name: body
required: true
schema: schema:
type: object type: string
properties: requestBody:
auth: content:
description: |- application/json:
Additional authentication information for the schema:
user-interactive authentication API. type: object
allOf: properties:
- "$ref": "definitions/auth_data.yaml" auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $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.
schema: content:
type: object application/json:
examples: schema:
application/json: { type: object
} examples:
401: response:
description: |- value: {}
The homeserver requires additional authentication information. "401":
schema: description: The homeserver requires additional authentication information.
"$ref": "definitions/auth_response.yaml" content:
application/json:
schema:
$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,42 +192,62 @@ 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: devices:
devices: type: array
type: array description: The list of device IDs to delete.
description: The list of device IDs to delete. items:
items: type: string
type: string description: A list of device IDs.
description: A list of device IDs. example:
example: ["QBUAZIFURK", "AUIECTSRND"] - QBUAZIFURK
auth: - AUIECTSRND
allOf: auth:
- "$ref": "definitions/auth_data.yaml" allOf:
description: |- - $ref: definitions/auth_data.yaml
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.
schema: content:
type: object application/json:
examples: schema:
application/json: { type: object
} examples:
401: response:
description: |- value: {}
The homeserver requires additional authentication information. "401":
schema: description: The homeserver requires additional authentication information.
"$ref": "definitions/auth_response.yaml" content:
application/json:
schema:
$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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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"
schema:
type: string
- in: path - in: path
type: string
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,78 +64,94 @@ 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
responses:
200:
description: The events and state surrounding the requested event.
schema: schema:
type: object type: string
description: The events and state surrounding the requested event. responses:
properties: "200":
start: description: The events and state surrounding the requested event.
type: string content:
description: |- application/json:
A token that can be used to paginate backwards with. schema:
end: type: object
type: string description: The events and state surrounding the requested event.
description: |- properties:
A token that can be used to paginate forwards with. start:
events_before: type: string
type: array description: A token that can be used to paginate backwards with.
description: |- end:
A list of room events that happened just before the type: string
requested event, in reverse-chronological order. description: A token that can be used to paginate forwards with.
items: events_before:
$ref: "definitions/client_event.yaml" type: array
event: description: |-
description: |- A list of room events that happened just before the
Details of the requested event. requested event, in reverse-chronological order.
allOf: items:
- $ref: "definitions/client_event.yaml" $ref: definitions/client_event.yaml
events_after: event:
type: array description: Details of the requested event.
description: |- allOf:
A list of room events that happened just after the - $ref: definitions/client_event.yaml
requested event, in chronological order. events_after:
items: type: array
$ref: "definitions/client_event.yaml" description: |-
state: A list of room events that happened just after the
type: array requested event, in chronological order.
description: |- items:
The state of the room at the last event returned. $ref: definitions/client_event.yaml
items: state:
$ref: "definitions/client_event.yaml" type: array
examples: description: The state of the room at the last event returned.
application/json: { items:
"end": "t29-57_2_0_2", $ref: definitions/client_event.yaml
"events_after": [ examples:
{ response:
"room_id": "!636q39766251:example.com", value: {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" "end": "t29-57_2_0_2",
} "events_after": [
], {
"event": { "room_id": "!636q39766251:example.com",
"event_id": "$f3h4d129462ha:example.com", "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
"room_id": "!636q39766251:example.com", }
"$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" ],
}, "event": {
"events_before": [ "event_id": "$f3h4d129462ha:example.com",
{ "room_id": "!636q39766251:example.com",
"room_id": "!636q39766251:example.com", "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml"
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" },
} "events_before": [
], {
"start": "t27-54_2_0_2", "room_id": "!636q39766251:example.com",
"state": [ "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
{ }
"room_id": "!636q39766251:example.com", ],
"$ref": "../../event-schemas/examples/m.room.create.yaml" "start": "t27-54_2_0_2",
}, "state": [
{ {
"room_id": "!636q39766251:example.com", "room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml" "$ref": "../../event-schemas/examples/m.room.create.yaml"
} },
] {
} "room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.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

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

128
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,46 +36,51 @@ paths:
If the user was invited to the room, the homeserver will append a If the user was invited to the room, the homeserver will append a
`m.room.member` event to the room. `m.room.member` event to the room.
operationId: inviteUser operationId: inviteUser
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - in: path
type: string
name: roomId name: roomId
description: The room identifier (not alias) to which to invite the user. description: The room identifier (not alias) to which to invite the user.
required: true required: true
x-example: "!d41d8cd:matrix.org" example: "!d41d8cd:matrix.org"
- in: body
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
"user_id": "@cheeky_monkey:matrix.org", content:
"reason": "Welcome to the team!" application/json:
} schema:
properties: type: object
user_id: example: {
type: string "user_id": "@cheeky_monkey:matrix.org",
description: The fully qualified user ID of the invitee. "reason": "Welcome to the team!"
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been invited to join the room, or was already invited to the room.
examples:
application/json: {
} }
schema: properties:
type: object user_id:
400: type: string
description: The fully qualified user ID of the invitee.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required: true
responses:
"200":
description: The user has been invited to join the room, or was already invited
to the room.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |- description: |-
The request is invalid. A meaningful `errcode` and description The request is invalid. A meaningful `errcode` and description
@ -98,9 +92,11 @@ paths:
- One or more users being invited to the room are residents of a - One or more users being invited to the room are residents of a
homeserver which does not support the requested room version. The homeserver which does not support the requested room version. The
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
schema: content:
"$ref": "definitions/errors/error.yaml" application/json:
403: schema:
$ref: definitions/errors/error.yaml
"403":
description: |- description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
@ -108,14 +104,36 @@ paths:
- The invitee is already a member of the room. - The invitee is already a member of the room.
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} schema:
schema: $ref: definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml" examples:
429: response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

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

File diff suppressed because it is too large Load diff

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

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

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

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

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

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

@ -11,48 +11,54 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
schema: content:
type: object application/json:
required: ["joined_rooms"] schema:
properties: type: object
joined_rooms: required:
type: array - joined_rooms
description: |- properties:
The ID of each room in which the user has `joined` membership. joined_rooms:
items: type: array
type: string description: The ID of each room in which the user has `joined` membership.
examples: items:
application/json: { type: string
"joined_rooms": [ examples:
"!foo:example.com" response:
] value: {
} "joined_rooms": [
"!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

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

@ -11,56 +11,56 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
schema: content:
type: object application/json:
properties: schema:
visibility: type: object
type: string properties:
enum: ['private', 'public'] visibility:
description: The visibility of the room in the directory. type: string
examples: enum:
application/json: { - private
"visibility": "public" - public
} description: The visibility of the room in the directory.
404: examples:
response:
value: {
"visibility": "public"
}
"404":
description: The room is not known to the server description: The room is not known to the server
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Room not found" $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
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
name: body
required: true
description: |-
The new visibility for the room on the room directory.
schema: schema:
type: object type: string
properties: requestBody:
visibility: content:
type: string application/json:
enum: ["private", "public"] schema:
description: |- type: object
The new visibility setting for the room. properties:
Defaults to 'public'. visibility:
example: { type: string
"visibility": "public" enum:
} - private
- public
description: |-
The new visibility setting for the room.
Defaults to 'public'.
example: {
"visibility": "public"
}
description: The new visibility for the room on the room directory.
required: true
responses: 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: examples:
response:
value: {}
"404":
description: The room is not known to the server description: The room is not known to the server
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Room not found" $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
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
type: integer description: Limit the number of results returned.
description: |- schema:
Limit the number of results returned. type: integer
- 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,35 +179,32 @@ 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
name: body
required: true
description: |-
Options for which rooms to return.
schema: schema:
type: object type: string
properties: requestBody:
limit: content:
type: integer application/json:
description: |- schema:
Limit the number of results returned. type: object
since: properties:
type: string limit:
description: |- type: integer
A pagination token from a previous request, allowing clients description: Limit the number of results returned.
to get the next (or previous) batch of rooms. The direction since:
of pagination is specified solely by which token is supplied, type: string
rather than via an explicit flag. description: |-
filter: A pagination token from a previous request, allowing clients
type: object to get the next (or previous) batch of rooms. The direction
title: "Filter" of pagination is specified solely by which token is supplied,
description: |- rather than via an explicit flag.
Filter to apply to the results. filter:
properties: type: object
title: Filter
description: Filter to apply to the results.
properties:
generic_search_term: generic_search_term:
type: string type: string
description: |- description: |-
@ -210,31 +220,50 @@ paths:
for. To include rooms without a room type, specify `null` within this for. To include rooms without a room type, specify `null` within this
list. When not specified, all applicable rooms (regardless of type) list. When not specified, all applicable rooms (regardless of type)
are returned. are returned.
include_all_networks: include_all_networks:
type: boolean type: boolean
description: |- description: |-
Whether or not to include all known networks/protocols from Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false. application services on the homeserver. Defaults to false.
example: false example: false
third_party_instance_id: third_party_instance_id:
type: string type: string
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,
"include_all_networks": false, "m.space"
"third_party_instance_id": "irc" ]
} },
"include_all_networks": false,
"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.
schema: content:
$ref: "definitions/public_rooms_response.yaml" application/json:
schema:
$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

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

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

@ -11,25 +11,15 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,55 +54,81 @@ 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: Additional authentication information for the user-interactive
description: |- authentication API.
Additional authentication information for the user-interactive 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:
} type: object
schema: required:
type: object - login_token
required: ["login_token", "expires_in_ms"] - expires_in_ms
properties: properties:
login_token: login_token:
type: string type: string
description: The login token for the `m.login.token` login flow. description: The login token for the `m.login.token` login flow.
expires_in_ms: expires_in_ms:
type: integer type: integer
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).
schema: content:
"$ref": "definitions/errors/error.yaml" application/json:
401: schema:
description: |- $ref: definitions/errors/error.yaml
The homeserver requires additional authentication information. "401":
schema: description: The homeserver requires additional authentication information.
"$ref": "definitions/auth_response.yaml" content:
429: application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

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

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

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

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,54 +32,61 @@ 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"
responses:
200:
description: "The events received, which may be none."
examples:
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
]
}
schema: schema:
type: object type: integer
properties: responses:
start: "200":
type: string description: The events received, which may be none.
description: |- content:
A token which correlates to the start of `chunk`. This application/json:
is usually the same token supplied to `from=`. schema:
end: type: object
type: string properties:
description: |- start:
A token which correlates to the end of `chunk`. This type: string
token should be used in the next request to `/events`. description: |-
chunk: A token which correlates to the start of `chunk`. This
type: array is usually the same token supplied to `from=`.
description: "An array of events." end:
items: type: string
$ref: "definitions/client_event.yaml" description: |-
400: A token which correlates to the end of `chunk`. This
description: "Bad pagination `from` parameter." token should be used in the next request to `/events`.
chunk:
type: array
description: An array of events.
items:
$ref: definitions/client_event.yaml
examples:
response:
value: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
"400":
description: Bad pagination `from` parameter.
tags: 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,176 +116,201 @@ 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"
responses:
200:
description: The user's current state.
examples:
application/json: {
"end": "s3456_9_0",
"presence": [
{"$ref": "../../event-schemas/examples/m.presence.yaml"}
],
"account_data": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
],
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
}
]
}
schema: schema:
type: object type: boolean
properties: responses:
end: "200":
type: string description: The user's current state.
description: |- content:
A token which correlates to the end of the timelines returned. This application/json:
token should be used with the `/events` endpoint to listen for new schema:
events. type: object
presence: properties:
type: array end:
description: A list of presence events. type: string
items: description: |-
$ref: "definitions/client_event.yaml" A token which correlates to the end of the timelines returned. This
rooms: token should be used with the `/events` endpoint to listen for new
type: array events.
items: presence:
type: object type: array
title: RoomInfo description: A list of presence events.
properties: items:
room_id: $ref: definitions/client_event.yaml
type: string rooms:
description: "The ID of this room." type: array
membership: items:
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 type: object
title: PaginationChunk title: RoomInfo
description: "The pagination chunk for this room."
properties: properties:
start: room_id:
type: string type: string
description: |- description: The ID of this room.
A token which correlates to the start of `chunk`. membership:
Can be passed to type: string
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages) description: The user's membership state in this room.
to retrieve earlier events. 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 If no earlier events are available, this property may be omitted from
the response. the response.
end: end:
type: string type: string
description: |- description: |-
A token which correlates to the end of `chunk`. A token which correlates to the end of `chunk`.
Can be passed to Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages) [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events. to retrieve later events.
chunk: 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 type: array
description: |- description: |-
If the user is a member of the room this will be a If the user is a member of the room this will be the
list of the most recent messages for this room. If current state of the room as a list of events. If the
the user has left the room this will be the user has left the room this will be the state of the
messages that preceded them leaving. This array room when they left it.
will consist of at most `limit` elements.
items: items:
$ref: "definitions/client_event.yaml" $ref: definitions/client_event.yaml
required: ["end", "chunk"] visibility:
state: type: string
type: array enum:
description: |- - private
If the user is a member of the room this will be the - public
current state of the room as a list of events. If the description: |-
user has left the room this will be the state of the Whether this room is visible to the `/publicRooms` API
room when they left it. or not."
items: account_data:
$ref: "definitions/client_event.yaml" type: array
visibility: description: |-
type: string The private data that this user has attached to
enum: ["private", "public"] this room.
description: |- items:
Whether this room is visible to the `/publicRooms` API $ref: definitions/client_event.yaml
or not." required:
account_data: - room_id
type: array - membership
description: |- account_data:
The private data that this user has attached to type: array
this room. description: The global private data created by this user.
items: items:
$ref: "definitions/client_event.yaml" title: Event
required: ["room_id", "membership"] type: object
account_data: allOf:
type: array - $ref: ../../event-schemas/schema/core-event-schema/event.yaml
description: |- required:
The global private data created by this user. - end
items: - rooms
title: Event - presence
type: object examples:
allOf: response:
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" value: {
required: ["end", "rooms", "presence"] "end": "s3456_9_0",
404: "presence": [
{
"$ref": "../../event-schemas/examples/m.presence.yaml"
}
],
"account_data": [
{
"type": "org.example.custom.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
],
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {
"tags": {
"work": {
"order": 1
}
}
}
},
{
"type": "org.example.custom.room.config",
"content": {
"custom_config_key": "custom_config_value"
}
}
]
}
]
}
"404":
description: There is no avatar URL for this user or this user does not exist. 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

81
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
name: body
description: An empty object. Reserved for future expansion.
required: true
schema: schema:
type: object type: string
example: {} requestBody:
content:
application/json:
schema:
type: object
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.
examples: content:
application/json: { application/json:
"access_token": "SomeT0kenHere", schema:
"token_type": "Bearer", $ref: definitions/openid_token.yaml
"matrix_server_name": "example.com", examples:
"expires_in": 3600, response:
} value: {
schema: "access_token": "SomeT0kenHere",
$ref: "definitions/openid_token.yaml" "token_type": "Bearer",
429: "matrix_server_name": "example.com",
"expires_in": 3600
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,62 +37,82 @@ 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"
- in: query
type: string
name: room_id
description: |-
The room ID for which events should be returned.
x-example:
- "!somewhere:over.the.rainbow"
responses:
200:
description: "The events received, which may be none."
examples:
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"room_id": "!somewhere:over.the.rainbow",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
schema: schema:
type: object type: integer
properties: - in: query
start: name: room_id
type: string description: The room ID for which events should be returned.
description: |- example:
A token which correlates to the first value in `chunk`. This - "!somewhere:over.the.rainbow"
is usually the same token supplied to `from=`. schema:
end: type: string
type: string responses:
description: |- "200":
A token which correlates to the last value in `chunk`. This description: The events received, which may be none.
token should be used in the next request to `/events`. content:
chunk: application/json:
type: array schema:
description: "An array of events." type: object
items: properties:
type: object start:
title: Event type: string
allOf: description: |-
- "$ref": "definitions/client_event.yaml" A token which correlates to the first value in `chunk`. This
400: is usually the same token supplied to `from=`.
description: "Bad pagination `from` parameter." end:
type: string
description: |-
A token which correlates to the last value in `chunk`. This
token should be used in the next request to `/events`.
chunk:
type: array
description: An array of events.
items:
type: object
title: Event
allOf:
- $ref: definitions/client_event.yaml
examples:
response:
value: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"room_id": "!somewhere:over.the.rainbow",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
"400":
description: Bad pagination `from` parameter.
tags: 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

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

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

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

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

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

File diff suppressed because it is too large Load diff

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
name: body
description: The read marker and optional read receipt locations.
required: true
schema: schema:
type: object type: string
properties: requestBody:
"m.fully_read": content:
type: string application/json:
description: |- schema:
The event ID the read marker should be located at. The type: object
event MUST belong to the room. properties:
example: "$somewhere:example.org" m.fully_read:
x-changedInMatrixVersion: type: string
1.4: | description: |-
This property is no longer required. The event ID the read marker should be located at. The
"m.read": event MUST belong to the room.
type: string example: $somewhere:example.org
description: |- x-changedInMatrixVersion:
The event ID to set the read receipt location at. This is "1.4": |
equivalent to calling `/receipt/m.read/$elsewhere:example.org` This property is no longer required.
and is provided here to save that extra call. m.read:
example: "$elsewhere:example.org" type: string
"m.read.private": description: |-
x-addedInMatrixVersion: "1.4" The event ID to set the read receipt location at. This is
type: string equivalent to calling `/receipt/m.read/$elsewhere:example.org`
description: |- and is provided here to save that extra call.
The event ID to set the *private* read receipt location at. This example: $elsewhere:example.org
equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` m.read.private:
and is provided here to save that extra call. x-addedInMatrixVersion: "1.4"
example: "$elsewhere:example.org" type: string
description: |-
The event ID to set the *private* read receipt location at. This
equivalent to calling `/receipt/m.read.private/$elsewhere:example.org`
and is provided here to save that extra call.
example: $elsewhere:example.org
description: The read marker and optional read receipt locations.
required: true
responses: 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:
schema: application/json:
type: object schema:
properties: {} type: object
429: properties: {}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

94
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,50 +36,71 @@ 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"
schema:
type: string
- in: path - in: path
type: string
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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Indecent material" "reason": "Indecent material"
} }
properties: properties:
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:
} type: object
schema: properties:
type: object event_id:
properties: type: string
event_id: description: A unique identifier for the event.
type: string examples:
description: |- response:
A unique identifier for the event. 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

145
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,63 +39,81 @@ 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: {
"refresh_token": "some_token" "refresh_token": "some_token"
} }
properties: properties:
refresh_token: refresh_token:
type: string type: string
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", schema:
"expires_in_ms": 60000, type: object
"refresh_token": "another_new_token" properties:
} access_token:
schema: type: string
type: object description: The new access token to use.
properties: refresh_token:
access_token: type: string
type: string description: |-
description: |- The new refresh token to use when the access token needs to
The new access token to use. be refreshed again. If not given, the old refresh token can
refresh_token: be re-used.
type: string expires_in_ms:
description: |- type: integer
The new refresh token to use when the access token needs to description: |-
be refreshed again. If not given, the old refresh token can The lifetime of the access token, in milliseconds. If not
be re-used. given, the client can assume that the access token will not
expires_in_ms: expire.
type: integer required:
description: |- - access_token
The lifetime of the access token, in milliseconds. If not examples:
given, the client can assume that the access token will not response:
expire. value: {
required: "access_token": "a_new_token",
- access_token "expires_in_ms": 60000,
401: "refresh_token": "another_new_token"
description: |- }
The provided token was unknown, or has already been used. "401":
examples: description: The provided token was unknown, or has already been used.
application/json: { content:
"errcode": "M_UNKNOWN_TOKEN", application/json:
"error": "Soft logged out", schema:
"soft_logout": true $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
429: "errcode": "M_UNKNOWN_TOKEN",
"error": "Soft logged out",
"soft_logout": true
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3

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

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

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

@ -11,21 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,41 +31,63 @@ 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.
responses: example: fBVFdqVE
200:
description: The check has a result.
examples:
application/json: {
"valid": true
}
schema: schema:
type: object type: string
properties: responses:
valid: "200":
type: boolean description: The check has a result.
description: |- content:
True if the token is still valid, false otherwise. This should application/json:
additionally be false if the token is not a recognised token by schema:
the server. type: object
required: ['valid'] properties:
403: valid:
type: boolean
description: |-
True if the token is still valid, false otherwise. This should
additionally be false if the token is not a recognised token by
the server.
required:
- valid
examples:
response:
value: {
"valid": true
}
"403":
description: |- 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.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "Registration is not enabled on this homeserver." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
429: "errcode": "M_FORBIDDEN",
"error": "Registration is not enabled on this homeserver."
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,43 +25,64 @@ 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"
schema:
type: string
- in: path - in: path
type: string
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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
"score": -100, content:
"reason": "this makes me sad" application/json:
} schema:
properties: type: object
score: example: {
type: integer "score": -100,
description: |- "reason": "this makes me sad"
The score to rate this content as where -100 is most offensive }
and 0 is inoffensive. properties:
reason: score:
type: string type: integer
description: The reason the content is being reported. May be blank. description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
reason:
type: string
description: The reason the content is being reported. May be blank.
required: true
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The event has been reported successfully. description: The event has been reported successfully.
schema: content:
type: object application/json:
examples: schema:
application/json: {} type: object
examples:
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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,64 +49,91 @@ 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:
schema: application/json:
type: object schema:
properties: type: object
event_id: properties:
type: string event_id:
description: |- type: string
The ID of the event found description: 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.
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:
examples: - event_id
application/json: { - origin_server_ts
"event_id": "$143273582443PhrSn:example.org", examples:
"origin_server_ts": 1432735824653 response:
} value: {
404: "event_id": "$143273582443PhrSn:example.org",
description: |- "origin_server_ts": 1432735824653
No event was found. }
examples: "404":
application/json: { description: No event was found.
"errcode": "M_NOT_FOUND", content:
"error": "Unable to find event from 1432684800000 in forward direction" application/json:
} schema:
schema: $ref: definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml" examples:
429: response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" 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/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -1,18 +1,7 @@
swagger: '2.0' openapi: 3.1.0
info: 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,127 +18,161 @@ 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"
responses:
200:
description: The current state of the room
examples:
application/json: {
"membership": "join",
"messages": {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!636q39766251:example.com",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [{
"type": "m.tag",
"content": {"tags": {"work": {"order": "1"}}}
}]
}
schema: schema:
title: RoomInfo type: string
type: object responses:
properties: "200":
room_id: description: The current state of the room
type: string content:
description: "The ID of this room." application/json:
membership: schema:
type: string title: RoomInfo
description: "The user's membership state in this room."
enum: ["invite", "join", "leave", "ban"]
messages:
type: object type: object
title: PaginationChunk
description: "The pagination chunk for this room."
properties: properties:
start: room_id:
type: string type: string
description: |- description: The ID of this room.
A token which correlates to the start of `chunk`. Can be passed to membership:
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages) type: string
to retrieve earlier events. 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 If no earlier events are available, this property may be omitted from
the response. the response.
end: end:
type: string type: string
description: |- description: |-
A token which correlates to the end of `chunk`. Can be passed to A token which correlates to the end of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages) [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
to retrieve later events. to retrieve later events.
chunk: 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 type: array
description: |- description: |-
If the user is a member of the room this will be a If the user is a member of the room this will be the
list of the most recent messages for this room. If current state of the room as a list of events. If the
the user has left the room this will be the user has left the room this will be the state of the
messages that preceded them leaving. This array room when they left it.
will consist of at most `limit` elements.
items: items:
"$ref": "definitions/client_event.yaml" $ref: definitions/client_event.yaml
required: ["end", "chunk"] visibility:
state: type: string
type: array enum:
description: |- - private
If the user is a member of the room this will be the - public
current state of the room as a list of events. If the description: |-
user has left the room this will be the state of the Whether this room is visible to the `/publicRooms` API
room when they left it. or not."
items: account_data:
"$ref": "definitions/client_event.yaml" type: array
visibility: description: The private data that this user has attached to this room.
type: string items:
enum: ["private", "public"] title: Event
description: |- type: object
Whether this room is visible to the `/publicRooms` API allOf:
or not." - $ref: ../../event-schemas/schema/core-event-schema/event.yaml
account_data: required:
type: array - room_id
description: |- examples:
The private data that this user has attached to this room. response:
items: value: {
title: Event "membership": "join",
type: object "messages": {
allOf: "chunk": [
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" {
required: ["room_id"] "room_id": "!636q39766251:example.com",
403: "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
description: > },
You aren't a member of the room and weren't previously a {
member of the room. "room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
}
],
"end": "s3456_9_0",
"start": "t44-3453_9_0"
},
"room_id": "!636q39766251:example.com",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
],
"visibility": "private",
"account_data": [
{
"type": "m.tag",
"content": {
"tags": {
"work": {
"order": "1"
}
}
}
}
]
}
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
tags: 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

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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"
schema:
type: string
- 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.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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
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:
} type: object
schema: properties:
type: object event_id:
properties: type: string
event_id: description: A unique identifier for the event.
type: string required:
description: |- - event_id
A unique identifier for the event. examples:
required: response:
- event_id value: {
400: "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).
schema: content:
"$ref": "definitions/errors/error.yaml" application/json:
schema:
$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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,62 +42,58 @@ 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"
schema:
type: string
- 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.room.member" example: m.room.member
schema:
type: string
- in: path - in: path
type: string
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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
example: {
"membership": "join", "membership": "join",
"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:
} type: object
schema: properties:
type: object event_id:
properties: type: string
event_id: description: A unique identifier for the event.
type: string required:
description: |- - event_id
A unique identifier for the event. examples:
required: response:
- event_id value: {
403: "event_id": "$YUwRidLecu:example.com"
description: |- }
The sender doesn't have permission to send the event into the room. "400":
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
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.
schema: content:
$ref: "definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: definitions/errors/error.yaml
"errcode": "M_BAD_ALIAS", examples:
"error": "The alias '#hello:example.org' does not point to this room." response:
} value: {
"errcode": "M_BAD_ALIAS",
"error": "The alias '#hello:example.org' does not point to this room."
}
"403":
description: The sender doesn't have permission to send the event into the room.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags: 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

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

@ -11,82 +11,99 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
name: body
required: true
schema: schema:
type: object type: string
properties: requestBody:
new_version: content:
type: string application/json:
description: The new version for the room. schema:
example: {"new_version": "2"} type: object
required: [new_version] properties:
new_version:
type: string
description: The new version for the room.
example: {
"new_version": "2"
}
required:
- new_version
required: true
responses: responses:
200: "200":
description: The room was successfully upgraded. description: The room was successfully upgraded.
examples: content:
application/json: { application/json:
"replacement_room": "!newroom:example.org" schema:
} type: object
schema: properties:
type: object replacement_room:
properties: type: string
replacement_room: description: The ID of the new room.
type: string required:
description: The ID of the new room. - replacement_room
required: [replacement_room] examples:
400: 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.
examples: content:
application/json: { application/json:
"errcode": "M_UNSUPPORTED_ROOM_VERSION", schema:
"error": "This server does not support that room version" $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
403: "errcode": "M_UNSUPPORTED_ROOM_VERSION",
description: |- "error": "This server does not support that room version"
The user is not permitted to upgrade the room. }
examples: "403":
application/json: { description: The user is not permitted to upgrade the room.
"errcode": "M_FORBIDDEN", content:
"error": "You cannot upgrade this room" application/json:
} schema:
schema: $ref: definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml" examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You cannot upgrade this room"
}
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

371
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"
schema:
type: string
- 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
schema:
type: string
responses: responses:
200: "200":
description: The full event. description: The full event.
examples: content:
application/json: { application/json:
"room_id": "!636q39766251:matrix.org", schema:
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" $ref: definitions/client_event.yaml
} examples:
schema: response:
"$ref": "definitions/client_event.yaml" value: {
404: "room_id": "!636q39766251:matrix.org",
description: The event was not found or you do not have permission to read this event. "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
examples: }
application/json: { "404":
"errcode": "M_NOT_FOUND", description: The event was not found or you do not have permission to read this
"error": "Event not found." event.
} content:
schema: application/json:
"$ref": "definitions/errors/error.yaml" schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
tags: tags:
- Room participation - Room participation
"/rooms/{roomId}/state/{eventType}/{stateKey}": "/rooms/{roomId}/state/{eventType}/{stateKey}":
@ -83,225 +81,260 @@ 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"
schema:
type: string
- in: path - in: path
type: string
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
schema:
type: string
- in: path - in: path
type: string
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: ""
responses:
200:
description: The content of the state event.
examples:
application/json: {
"name": "Example room name"}
schema: schema:
type: object type: string
404: responses:
"200":
description: The content of the state event.
content:
application/json:
schema:
type: object
examples:
response:
value: {
"name": "Example room name"
}
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
"404":
description: The room has no state with the given type or key. 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"
responses:
200:
description: The current state of the room
examples:
application/json: [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
]
schema: schema:
type: array type: string
title: RoomState responses:
description: |- "200":
If the user is a member of the room this will be the description: The current state of the room
current state of the room as a list of events. If the user content:
has left the room then this will be the state of the room application/json:
when they left as a list of events. schema:
items: type: array
$ref: "definitions/client_event.yaml" title: RoomState
403: description: |-
description: > If the user is a member of the room this will be the
You aren't a member of the room and weren't previously a current state of the room as a list of events. If the user
member of the room. has left the room then this will be the state of the room
when they left as a list of events.
items:
$ref: definitions/client_event.yaml
examples:
response:
value: [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.create.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
}
]
"403":
description: |
You aren't a member of the room and weren't previously a member of the room.
tags: 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
schema:
type: string
enum:
- join
- invite
- knock
- leave
- ban
- in: query - in: query
name: not_membership name: not_membership
type: string
enum:
- join
- invite
- knock
- leave
- ban
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.
examples: content:
application/json: { application/json:
"chunk": [ schema:
{ type: object
"room_id": "!636q39766251:example.com", properties:
"$ref": "../../event-schemas/examples/m.room.member.yaml" chunk:
type: array
items:
$ref: definitions/client_event.yaml
examples:
response:
value: {
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.member.yaml"
}
]
} }
] "403":
} description: |
schema: You aren't a member of the room and weren't previously a member of the room.
type: object
properties:
chunk:
type: array
items:
$ref: "definitions/client_event.yaml"
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags: tags:
- Room participation - Room participation
"/rooms/{roomId}/joined_members": "/rooms/{roomId}/joined_members":
get: get:
summary: Gets the list of currently joined users and their profile data. summary: Gets the list of currently joined users and their profile data.
description: description: This API returns a map of MXIDs to member info objects for members
This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. of the room. The current user must be in the room for it to work, unless
This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. it is an Application Service in which case any of the AS's users must be
in the room. This API is primarily for Application Services and should
be faster to respond than `/members` as it can be implemented more
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: { schema:
"joined": {
"@bar:example.com": {
"display_name": "Bar",
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
}
}
}
schema:
type: object
properties:
joined:
additionalProperties:
title: RoomMember
type: object
properties:
display_name:
type: string
description: The display name of the user this object is representing.
avatar_url:
type: string
format: uri
description: The avatar of the user this object is representing, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris).
description: A map from user ID to a RoomMember object.
type: object type: object
403: properties:
description: > joined:
additionalProperties:
title: RoomMember
type: object
properties:
display_name:
type: string
description: The display name of the user this object is representing.
avatar_url:
type: string
format: uri
description: The avatar of the user this object is representing, as an [`mxc://`
URI](/client-server-api/#matrix-content-mxc-uris).
description: A map from user ID to a RoomMember object.
type: object
examples:
response:
value: {
"joined": {
"@bar:example.com": {
"display_name": "Bar",
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
}
}
}
"403":
description: |
You aren't a member of the room. 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

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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
schema:
type: integer
- in: query - in: query
type: integer
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,91 +66,117 @@ 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
responses:
200:
description: |-
A portion of the space tree, starting at the provided room ID.
examples:
application/json: {
"rooms": [
{
"room_id": "!space:example.org",
"avatar_url": "mxc://example.org/abcdef",
"guest_can_join": false,
"name": "The First Space",
"topic": "No other spaces were created first, ever",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space",
"num_joined_members": 42,
"canonical_alias": "#general:example.org",
"children_state": [
{
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": ["example.org"]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
}
]
}
],
"next_batch": "next_batch_token"
}
schema: schema:
type: object type: string
properties: responses:
rooms: "200":
type: array description: A portion of the space tree, starting at the provided room ID.
description: |- content:
The rooms for the current page, with the current filters. application/json:
items: schema:
allOf: type: object
- $ref: "definitions/public_rooms_chunk.yaml" properties:
- type: object rooms:
title: ChildRoomsChunk type: array
properties: description: The rooms for the current page, with the current filters.
# Override x-addedInMatrixVersion for room_type (this endpoint had it first) items:
room_type: allOf:
type: string - $ref: definitions/public_rooms_chunk.yaml
description: |- - type: object
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. title: ChildRoomsChunk
children_state: properties:
type: array room_type:
description: |- type: string
The [`m.space.child`](#mspacechild) events of the space-room, represented description: The `type` of room (from
as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. [`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. If the room is not a space-room, this should be empty.
items: items:
allOf: allOf:
- $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
- type: object - type: object
title: StrippedChildStateEvent title: StrippedChildStateEvent
properties: properties:
origin_server_ts: origin_server_ts:
type: integer type: integer
format: int64 format: int64
description: The `origin_server_ts` for the event. description: The `origin_server_ts` for the event.
required: [origin_server_ts] required:
required: [children_state] - origin_server_ts
next_batch: required:
type: string - children_state
description: |- next_batch:
A token to supply to `from` to keep paginating the responses. Not present when there are type: string
no further results. description: |-
required: [rooms] A token to supply to `from` to keep paginating the responses. Not present when there are
403: no further results.
required:
- rooms
examples:
response:
value: {
"rooms": [
{
"room_id": "!space:example.org",
"avatar_url": "mxc://example.org/abcdef",
"guest_can_join": false,
"name": "The First Space",
"topic": "No other spaces were created first, ever",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space",
"num_joined_members": 42,
"canonical_alias": "#general:example.org",
"children_state": [
{
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": [
"example.org"
]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
}
]
}
],
"next_batch": "next_batch_token"
}
"400":
description: |-
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The `from` token is unknown to the server.
- `suggested_only` or `max_depth` changed during pagination.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "suggested_only and max_depth cannot change on paginated requests"
}
"403":
description: |- 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.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "You are not allowed to view this room." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
400: "errcode": "M_FORBIDDEN",
description: |- "error": "You are not allowed to view this room."
The request was invalid in some way. A meaningful `errcode` }
and description error text will be returned. Example reasons for rejection are: "429":
- 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.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

@ -11,17 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,20 +30,22 @@ 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}":
get: get:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
@ -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.
schema:
type: string
- 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:
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

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

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

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

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

@ -11,23 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,41 +27,48 @@ paths:
security: security:
- accessToken: [] - accessToken: []
responses: responses:
200: "200":
description: The protocols supported by the homeserver. description: The protocols supported by the homeserver.
schema: content:
$ref: ../application-service/definitions/protocol_metadata.yaml application/json:
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
tags: tags:
- Third-party Lookup - Third-party Lookup
"/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.
schema: content:
$ref: ../application-service/definitions/protocol.yaml application/json:
404: schema:
$ref: ../application-service/definitions/protocol.yaml
"404":
description: The protocol is unknown. description: The protocol is unknown.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND" schema:
} $ref: definitions/errors/error.yaml
schema: examples:
$ref: definitions/errors/error.yaml 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.
schema: content:
$ref: ../application-service/definitions/location_batch.yaml application/json:
404: schema:
$ref: ../application-service/definitions/location_batch.yaml
"404":
description: No portal rooms were found. description: No portal rooms were found.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND" schema:
} $ref: definitions/errors/error.yaml
schema: examples:
$ref: definitions/errors/error.yaml 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...
type: string description: One or more custom fields that are passed to the AS to help
description: |- identify the user.
One or more custom fields that are passed to the AS 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.
schema: content:
$ref: ../application-service/definitions/user_batch.yaml application/json:
404: schema:
$ref: ../application-service/definitions/user_batch.yaml
"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:
} $ref: definitions/errors/error.yaml
schema: examples:
$ref: definitions/errors/error.yaml 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:
schema: application/json:
$ref: ../application-service/definitions/location_batch.yaml schema:
404: $ref: ../application-service/definitions/location_batch.yaml
"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:
} $ref: definitions/errors/error.yaml
schema: examples:
$ref: definitions/errors/error.yaml 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:
schema: application/json:
$ref: ../application-service/definitions/user_batch.yaml schema:
404: $ref: ../application-service/definitions/user_batch.yaml
"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:
} $ref: definitions/errors/error.yaml
schema: examples:
$ref: definitions/errors/error.yaml 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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,56 +60,64 @@ 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
name: body
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
example: {
"id_server": "matrix.org", "id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString", "id_access_token": "abc123_OpaqueString",
"medium": "email", "medium": "email",
"address": "cheeky@monkey.com" "address": "cheeky@monkey.com"
} }
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
id_access_token: third-party identifier lookups.
type: string id_access_token:
description: |- type: string
An access token previously registered with the identity server. Servers description: |-
can treat this as optional to distinguish between r0.5-compatible clients An access token previously registered with the identity server. Servers
and this specification version. can treat this as optional to distinguish between r0.5-compatible clients
medium: and this specification version.
type: string medium:
description: |- type: string
The kind of address being passed in the address field, for example description: |-
`email` (see [the list of recognised values](/appendices/#3pid-types)). The kind of address being passed in the address field, for example
address: `email` (see [the list of recognised values](/appendices/#3pid-types)).
type: string address:
description: The invitee's third-party identifier. type: string
required: ["id_server", "id_access_token", "medium", "address"] description: The invitee's third-party identifier.
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 examples:
403: response:
value: {}
"403":
description: |- description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
@ -128,14 +125,36 @@ paths:
- The invitee is already a member of the room. - The invitee is already a member of the room.
- The inviter is not currently in the room. - The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room. - The inviter's power level is insufficient to invite users to the room.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} schema:
schema: $ref: definitions/errors/error.yaml
"$ref": "definitions/errors/error.yaml" examples:
429: response:
value: {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,67 +30,97 @@ 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"
schema:
type: string
- in: query - in: query
type: string
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
responses:
200:
description: |-
A portion of the available thread roots in the room, based on the filter criteria.
examples:
application/json: {
"chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }],
"next_batch": "next_batch_token"
}
schema: schema:
type: object type: string
properties: responses:
chunk: "200":
type: array description: A portion of the available thread roots in the room, based on the
description: |- filter criteria.
The thread roots, ordered by the `latest_event` in each event's aggregated children. All events content:
returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). application/json:
schema:
type: object
properties:
chunk:
type: array
description: |-
The thread roots, ordered by the `latest_event` in each event's aggregated children. All events
returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events).
If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the
event is returned redacted to the caller. This is to simulate the same behaviour of a client doing 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.
examples: content:
application/json: { application/json:
"errcode": "M_FORBIDDEN", schema:
"error": "You are not allowed to view this room." $ref: definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "definitions/errors/error.yaml" value: {
400: "errcode": "M_FORBIDDEN",
description: |- "error": "You are not allowed to view this room."
The request was invalid in some way. A meaningful `errcode` }
and description error text will be returned. Example reasons for rejection are: "429":
- 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.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

@ -11,22 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,54 +27,72 @@ 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
name: body
required: true
schema: schema:
type: object type: string
title: body requestBody:
properties: content:
messages: application/json:
type: object schema:
description: |- type: object
The messages to send. A map from user ID, to a map from title: body
device ID to message body. The device ID may also be `*`, properties:
meaning all known devices for the user. messages:
additionalProperties:
type: object type: object
description: |-
The messages to send. A map from user ID, to a map from
device ID to message body. The device ID may also be `*`,
meaning all known devices for the user.
additionalProperties: additionalProperties:
type: object type: object
title: EventContent additionalProperties:
description: Message content type: object
example: { title: EventContent
"@alice:example.com": { description: Message content
"TLLBEANAAG": { example:
"example_content_key": "value" "@alice:example.com":
} TLLBEANAAG:
} example_content_key: value
} required:
required: ["messages"] - messages
required: true
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

98
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,48 +29,71 @@ 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"
schema:
type: string
- in: path - in: path
type: string
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
name: typingState
description: The current typing state.
required: true
schema: schema:
type: object type: string
example: { requestBody:
content:
application/json:
schema:
type: object
example: {
"typing": true, "typing": true,
"timeout": 30000 "timeout": 30000
} }
properties: properties:
typing: typing:
type: boolean type: boolean
description: |- description: |-
Whether the user is typing or not. If `false`, the `timeout` Whether the user is typing or not. If `false`, the `timeout`
key can be omitted. key can be omitted.
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 examples:
429: response:
value: {}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" 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

163
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,67 +33,93 @@ 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:
required: ["search_term"] - search_term
required: true
responses: responses:
200: "200":
description: The results of the search. description: The results of the search.
examples: content:
application/json: { application/json:
"results": [ schema:
{ type: object
"user_id": "@foo:bar.com", required:
"display_name": "Foo", - results
"avatar_url": "mxc://bar.com/foo" - limited
} properties:
], results:
"limited": false type: array
} description: Ordered by rank and then whether or not profile info is available.
schema: items:
type: object title: User
required: ["results", "limited"] type: object
properties: required:
results: - user_id
type: array properties:
description: Ordered by rank and then whether or not profile info is available. user_id:
items: type: string
title: User example: "@foo:bar.com"
type: object description: The user's matrix user ID.
required: ["user_id"] display_name:
properties: type: string
user_id: example: Foo
type: string description: The display name of the user, if one exists.
example: "@foo:bar.com" avatar_url:
description: The user's matrix user ID. type: string
display_name: format: uri
type: string example: mxc://bar.com/foo
example: "Foo" description: The avatar url, as an [`mxc://`
description: The display name of the user, if one exists. URI](/client-server-api/#matrix-content-mxc-uris),
avatar_url: if one exists.
type: string limited:
format: uri type: boolean
example: "mxc://bar.com/foo" description: Indicates if the result list has been truncated by the limit.
description: The avatar url, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris), if one exists. examples:
limited: response:
type: boolean value: {
description: Indicates if the result list has been truncated by the limit. "results": [
429: {
"user_id": "@foo:bar.com",
"display_name": "Foo",
"avatar_url": "mxc://bar.com/foo"
}
],
"limited": false
}
"429":
description: This request was rate-limited. description: This request was rate-limited.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

86
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,33 +40,52 @@ 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"], schema:
"unstable_features": {
"org.example.my_feature": true
}
}
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions
unstable_features:
type: object type: object
description: |- properties:
Experimental features the server supports. Features not listed here, versions:
or the lack of this property all together, indicate that a feature is type: array
not supported. description: The supported versions.
additionalProperties: items:
type: boolean type: string
description: Whether or not the namespaced feature is supported. description: The supported versions
required: ['versions'] unstable_features:
type: object
description: |-
Experimental features the server supports. Features not listed here,
or the lack of this property all together, indicate that a feature is
not supported.
additionalProperties:
type: boolean
description: Whether or not the namespaced feature is supported.
required:
- versions
examples:
response:
value: {
"versions": [
"r0.0.1",
"v1.1"
],
"unstable_features": {
"org.example.my_feature": true
}
}
tags: 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

111
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,42 +26,64 @@ 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", schema:
"password":"JlKfBy1QwLrO20385QyAtEyIv0=", type: object
"uris":[ properties:
"turn:turn.example.com:3478?transport=udp", username:
"turn:10.20.30.40:3478?transport=tcp", type: string
"turns:10.20.30.40:443?transport=tcp" description: The username to use.
], password:
"ttl":86400 type: string
} description: The password to use.
schema: uris:
type: object type: array
properties: items:
username: type: string
type: string description: A list of TURN URIs
description: |- ttl:
The username to use. type: integer
password: description: The time-to-live in seconds
type: string required:
description: |- - username
The password to use. - password
uris: - uris
type: array - ttl
items: examples:
type: string response:
description: A list of TURN URIs value: {
ttl: "username": "1443779631:@user:example.com",
type: integer "password": "JlKfBy1QwLrO20385QyAtEyIv0=",
description: The time-to-live in seconds "uris": [
required: ["username", "password", "uris", "ttl"] "turn:turn.example.com:3478?transport=udp",
429: "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.
schema: content:
"$ref": "definitions/errors/rate_limited.yaml" application/json:
schema:
$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

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

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

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

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

186
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,64 +24,74 @@ 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:
} type: object
schema: properties:
type: object token:
properties: type: string
token: description: |-
type: string An opaque string representing the token to authenticate future
description: |- requests to the identity server with.
An opaque string representing the token to authenticate future required:
requests to the identity server with. - token
required: ['token'] examples:
"/account": 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:
} type: object
schema: properties:
type: object user_id:
properties: type: string
user_id: description: The user ID which registered the token.
type: string required:
description: The user ID which registered the token. - user_id
required: ['user_id'] examples:
403: 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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"/account/logout": "errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/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: examples:
description: |- response:
The token is not registered or is otherwise unknown to the server. value: {}
examples: "401":
application/json: { description: The token is not registered or is otherwise unknown to the server.
"errcode": "M_UNKNOWN_TOKEN", content:
"error": "Unrecognised access token" application/json:
} schema:
schema: $ref: ../client-server/definitions/errors/error.yaml
$ref: "../client-server/definitions/errors/error.yaml" examples:
403: response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
"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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,22 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
schema: content:
$ref: "definitions/sid.yaml" application/json:
400: schema:
$ref: definitions/sid.yaml
"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.
examples: content:
application/json: { application/json:
"errcode": "M_INVALID_EMAIL", schema:
"error": "The email address is not valid" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
403: "errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
"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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"/validate/email/submitToken": "errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/validate/email/submitToken:
post: post:
summary: Validate ownership of an email address. summary: Validate ownership of an email address.
description: |- description: |-
@ -110,53 +108,63 @@ 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: {
"sid": "1234", "sid": "1234",
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"token": "atoken" "token": "atoken"
} }
properties: properties:
sid: sid:
type: string type: string
description: The session ID, generated by the `requestToken` call. description: The session ID, generated by the `requestToken` call.
client_secret: client_secret:
type: string type: string
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: { schema:
"success": true type: object
} properties:
schema: success:
type: object type: boolean
properties: description: Whether the validation was successful or not.
success: required:
type: boolean - success
description: Whether the validation was successful or not. examples:
required: ['success'] response:
403: 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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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
schema:
type: string
- in: query - in: query
type: string
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
schema:
type: string
- in: query - in: query
type: string
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

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

@ -12,22 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,76 +28,108 @@ 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: {
"mxid": "@foo:bar.com", "mxid": "@foo:bar.com",
"token": "sometoken", "token": "sometoken",
"private_key": "base64encodedkey" "private_key": "base64encodedkey"
} }
properties: properties:
mxid: mxid:
type: string type: string
description: The Matrix user ID of the user accepting the invitation. description: The Matrix user ID of the user accepting the invitation.
token: token:
type: string type: string
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.
schema: content:
type: object application/json:
properties: schema:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
type: object type: object
description: The signature of the mxid, sender, and token. properties:
allOf: mxid:
- $ref: "../../schemas/server-signatures.yaml" type: string
token: description: The Matrix user ID of the user accepting the invitation.
type: string sender:
description: The token for the invitation. type: string
required: ['mxid', 'sender', 'signatures', 'token'] description: The Matrix user ID of the user who sent the invitation.
examples: signatures:
application/json: { type: object
"mxid": "@foo:bar.com", description: The signature of the mxid, sender, and token.
"sender": "@baz:bar.com", allOf:
"signatures": { - $ref: ../../schemas/server-signatures.yaml
"my.id.server": { token:
"ed25519:0": "def987" type: string
} description: The token for the invitation.
}, required:
"token": "abc123" - mxid
} - sender
404: - signatures
description: The token was not found. - token
examples: examples:
application/json: { response:
"errcode": "M_UNRECOGNIZED", value: {
"error": "Didn't recognize token" "mxid": "@foo:bar.com",
} "sender": "@baz:bar.com",
schema: "signatures": {
$ref: "../client-server/definitions/errors/error.yaml" "my.id.server": {
403: "ed25519:0": "def987"
}
},
"token": "abc123"
}
"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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The token was not found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -15,22 +15,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,33 +29,39 @@ 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", schema:
"algorithms": ["none", "sha256"] type: object
} properties:
schema: lookup_pepper:
type: object type: string
properties: description: |-
lookup_pepper: The pepper the client MUST use in hashing identifiers, and MUST
type: string supply to the `/lookup` endpoint when performing lookups.
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the `/lookup` endpoint when performing lookups.
Servers SHOULD rotate this string often. Servers SHOULD rotate this string often.
algorithms: algorithms:
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,78 +71,95 @@ 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:
algorithm: algorithm:
type: string
description: |-
The algorithm the client is using to encode the `addresses`. This
should be one of the available options from `/hash_details`.
example: "sha256"
pepper:
type: string
description: |-
The pepper from `/hash_details`. This is required even when the
`algorithm` does not make use of it.
example: "matrixrocks"
addresses:
type: array
items:
type: string type: string
description: |- description: |-
The addresses to look up. The format of the entries here depend on The algorithm the client is using to encode the `addresses`. This
the `algorithm` used. Note that queries which have been incorrectly should be one of the available options from `/hash_details`.
hashed or formatted will lead to no matches. example: sha256
pepper:
type: string
description: |-
The pepper from `/hash_details`. This is required even when the
`algorithm` does not make use of it.
example: matrixrocks
addresses:
type: array
items:
type: string
description: |-
The addresses to look up. The format of the entries here depend on
the `algorithm` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
Note that addresses are case sensitive: review the 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: { schema:
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
schema:
type: object
properties:
mappings:
type: object type: object
description: |- properties:
Any applicable mappings of `addresses` to Matrix User IDs. Addresses mappings:
which do not have associations will not be included, which can make type: object
this property be an empty object. description: |-
title: AssociatedMappings Any applicable mappings of `addresses` to Matrix User IDs. Addresses
additionalProperties: which do not have associations will not be included, which can make
type: string this property be an empty object.
required: ['mappings'] title: AssociatedMappings
400: additionalProperties:
description: type: string
The client's request was invalid in some way. One possible problem could required:
be the `pepper` being invalid after the server has rotated it - this is - mappings
presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make examples:
a call to `/hash_details` to get a new pepper in this scenario, being response:
careful to avoid retry loops. value: {
"mappings": {
`M_INVALID_PARAM` can also be returned to indicate the client supplied "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
an `algorithm` that is unknown to the server. }
examples: }
application/json: { "400":
"errcode": "M_INVALID_PEPPER", description: |-
"error": "Unknown or invalid pepper - has it been rotated?" The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops.
} `M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PEPPER",
"error": "Unknown or invalid pepper - has it been rotated?"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,22 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
schema: content:
$ref: "definitions/sid.yaml" application/json:
400: schema:
$ref: definitions/sid.yaml
"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.
examples: content:
application/json: { application/json:
"errcode": "M_INVALID_ADDRESS", schema:
"error": "The phone number is not valid" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
403: "errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
"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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"/validate/msisdn/submitToken": "errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/validate/msisdn/submitToken:
post: post:
summary: Validate ownership of a phone number. summary: Validate ownership of a phone number.
description: |- description: |-
@ -112,53 +110,63 @@ 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: {
"sid": "1234", "sid": "1234",
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"token": "atoken" "token": "atoken"
} }
properties: properties:
sid: sid:
type: string type: string
description: The session ID, generated by the `requestToken` call. description: The session ID, generated by the `requestToken` call.
client_secret: client_secret:
type: string type: string
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: { schema:
"success": true type: object
} properties:
schema: success:
type: object type: boolean
properties: description: Whether the validation was successful or not.
success: required:
type: boolean - success
description: Whether the validation was successful or not. examples:
required: ['success'] response:
403: 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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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
schema:
type: string
- in: query - in: query
type: string
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
schema:
type: string
- in: query - in: query
type: string
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

40
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

172
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: { schema:
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" type: object
} properties:
schema: public_key:
type: object type: string
properties: description: Unpadded Base64 encoded public key.
public_key: required:
type: string - public_key
description: Unpadded Base64 encoded public key. examples:
required: ['public_key'] response:
404: value: {
description: "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
The public key was not found. }
examples: "404":
application/json: { description: The public key was not found.
"errcode": "M_NOT_FOUND", content:
"error": "The public key was not found" application/json:
} schema:
schema: $ref: ../client-server/definitions/errors/error.yaml
$ref: "../client-server/definitions/errors/error.yaml" examples:
"/pubkey/isvalid": response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
/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"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema: schema:
type: object type: string
properties: responses:
valid: "200":
type: boolean description: The validity of the public key.
description: Whether the public key is recognised and is currently valid. content:
required: ['valid'] application/json:
"/pubkey/ephemeral/isvalid": schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required:
- valid
examples:
response:
value: {
"valid": true
}
/pubkey/ephemeral/isvalid:
get: 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"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema: schema:
type: object type: string
properties: responses:
valid: "200":
type: boolean description: The validity of the public key.
description: Whether the public key is recognised and is currently valid. content:
required: ['valid'] application/json:
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required:
- valid
examples:
response:
value: {
"valid": true
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2

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

@ -12,22 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,142 +52,176 @@ 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
example: "!something:example.org" example: "!something:example.org"
sender: sender:
type: string type: string
description: The Matrix user ID of the inviting user description: The Matrix user ID of the inviting user
example: "@bob:example.com" example: "@bob:example.com"
room_alias: room_alias:
type: string type: string
description: |- description: |-
The Matrix room alias for the room to which the user is The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias` invited. This should be retrieved from the `m.room.canonical_alias`
state event. state event.
example: "#somewhere:example.org" example: "#somewhere:example.org"
room_avatar_url: room_avatar_url:
type: string type: string
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.
room_type: example: mxc://example.org/an0th3rM3dia
type: string room_type:
description: |- type: string
The `type` from the `m.room.create` event's `content`. If the create event doesn't description: |-
have a specified `type`, this field is not included. The `type` from the `m.room.create` event's `content`. If the create event doesn't
example: "m.space" have a specified `type`, this field is not included.
required: ["medium", "address", "room_id", "sender"] example: m.space
required:
- medium
- address
- room_id
- sender
responses: responses:
200: "200":
description: The invitation was stored. description: The invitation was stored.
schema: content:
type: object application/json:
properties: schema:
token: type: object
type: string properties:
description: | token:
The generated token. Must be a string consisting of the type: string
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed description: |
255 characters and it must not be empty. The generated token. Must be a string consisting of the
public_keys: characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
type: array 255 characters and it must not be empty.
description: | public_keys:
A list of [server's long-term public key, generated ephemeral type: array
public key]. description: |
items: A list of [server's long-term public key, generated ephemeral
type: object public key].
title: PublicKey items:
properties: type: object
public_key: title: PublicKey
type: string properties:
description: | public_key:
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). type: string
key_validity_url: description: |
type: string The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
description: | key_validity_url:
The URI of an endpoint where the validity of this key can be checked type: string
by passing it as a `public_key` query parameter. See description: |
[key management](/identity-service-api/#key-management). The URI of an endpoint where the validity of this key can be checked
required: ['public_key', 'key_validity_url'] by passing it as a `public_key` query parameter. See
display_name: [key management](/identity-service-api/#key-management).
type: string required:
description: The generated (redacted) display name. - public_key
required: ['token', 'public_keys', 'display_name'] - key_validity_url
examples: display_name:
application/json: { type: string
"token": "sometoken", description: The generated (redacted) display name.
"public_keys": [ required:
{ - token
"public_key": "serverPublicKeyBase64", - public_keys
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" - display_name
}, examples:
{ response:
"public_key": "ephemeralPublicKeyBase64", value: {
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" "token": "sometoken",
} "public_keys": [
], {
"display_name": "f...@b..." "public_key": "serverPublicKeyBase64",
} "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
400: },
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
"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`.
examples: content:
application/json: { application/json:
"errcode": "M_THREEPID_IN_USE", schema:
"error": "Binding already known", $ref: ../client-server/definitions/errors/error.yaml
"mxid": "@alice:example.com" examples:
} response:
schema: value: {
$ref: "../client-server/definitions/errors/error.yaml" "errcode": "M_THREEPID_IN_USE",
403: "error": "Binding already known",
"mxid": "@alice:example.com"
}
"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).
examples: content:
application/json: { application/json:
"errcode": "M_TERMS_NOT_SIGNED", schema:
"error": "Please accept our updated terms of service before continuing" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
$ref: "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,22 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,81 +24,85 @@ 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: |- description: The terms of service offered by the server.
The terms of service offered by the server. content:
examples: application/json:
application/json: { schema:
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
schema:
type: object
properties:
policies:
type: object type: object
title: Policy Map properties:
description: |- policies:
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required: ['version']
# TODO: TravisR - Make this render
additionalProperties:
type: object type: object
title: Internationalised Policy title: Policy Map
description: |- description: |-
The policy information for the specified language. The policies the server offers. Mapped from arbitrary ID (unused in
properties: this version of the specification) to a Policy Object.
name: additionalProperties:
type: string type: object
description: The translated name of the policy. title: Policy Object
url: description: |-
type: string The policy. Includes a map of language (ISO 639-2) to language-specific
description: |- policy information.
The URL, which should include the policy ID, version, and language properties:
in it, to be presented to the user as the policy. URLs should have version:
all three criteria to avoid conflicts when the policy is updated type: string
in the future: for example, if this was "https://example.org/terms.html" description: |-
then the server would be unable to update it because the client would The version for the policy. There are no requirements on what this
have already added that URL to the `m.accepted_terms` collection. might be and could be "alpha", semantically versioned, or arbitrary.
required: ['name', 'url'] required:
required: ['policies'] - version
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy
description: The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the `m.accepted_terms` collection.
required:
- name
- url
required:
- policies
examples:
response:
value: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
post: post:
summary: Indicates acceptance of terms to the server. summary: Indicates acceptance of terms to the server.
description: |- description: |-
@ -126,24 +120,43 @@ 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:
user_accepts: user_accepts:
type: array type: array
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

64
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,19 +30,39 @@ 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:
} type: object
schema: properties:
type: object versions:
properties: type: array
versions: description: The supported versions.
type: array items:
description: The supported versions. type: string
items: description: The supported versions.
type: string required:
description: The supported versions. - versions
required: ['versions'] examples:
response:
value: {
"versions": [
"r0.2.0",
"r0.2.1",
"v1.1"
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

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

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

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
type: array
items:
type: string
description: The event IDs to backfill from. description: The event IDs to backfill from.
required: true required: true
x-example: ["$abc123:matrix.org"] example:
- $abc123:matrix.org
schema:
type: array
items:
type: string
- 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.
schema: content:
$ref: "definitions/unlimited_pdu_transaction.yaml" application/json:
schema:
$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,58 +81,85 @@ 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
name: body
schema: schema:
type: object type: string
properties: requestBody:
limit: content:
type: integer application/json:
description: The maximum number of events to retrieve. Defaults to 10. schema:
example: 10 type: object
min_depth: properties:
type: integer limit:
description: The minimum depth of events to retrieve. Defaults to 0. type: integer
example: 0 description: The maximum number of events to retrieve. Defaults to 10.
earliest_events: example: 10
type: array min_depth:
description: |- type: integer
The latest event IDs that the sender already has. These are skipped when retrieving description: The minimum depth of events to retrieve. Defaults to 0.
the previous events of `latest_events`. example: 0
items: earliest_events:
type: string type: array
example: ["$missing_event:example.org"] description: |-
latest_events: The latest event IDs that the sender already has. These are skipped when retrieving
type: array the previous events of `latest_events`.
description: The event IDs to retrieve the previous events for. items:
items: type: string
type: string example:
example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"] - $missing_event:example.org
required: ['earliest_events', 'latest_events'] latest_events:
type: array
description: The event IDs to retrieve the previous events for.
items:
type: string
example:
- $event_that_has_the_missing_event_as_a_previous_event:example.org
required:
- earliest_events
- latest_events
responses: 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`.
schema: content:
type: object application/json:
properties: schema:
events: type: object
type: array properties:
description: |- events:
The missing events. The event format varies depending on the room version - check type: array
the [room version specification](/rooms) for precise event formats. description: |-
items: The missing events. The event format varies depending on the room version - check
type: object the [room version specification](/rooms) for precise event formats.
title: PDU items:
required: ['events'] type: object
examples: title: PDU
application/json: { required:
"events": [ - events
{"$ref": "examples/minimal_pdu.json"} examples:
] response:
} value: {
"events": [
{
"$ref": "examples/minimal_pdu.json"
}
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

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

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

@ -11,60 +11,68 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
responses:
200:
description: The auth chain for the event.
schema: schema:
type: object type: string
properties: responses:
auth_chain: "200":
type: array description: The auth chain for the event.
description: |- content:
The [PDUs](/server-server-api/#pdus) forming the auth chain application/json:
of the given event. The event format varies depending on the schema:
room version - check the [room version specification](/rooms) type: object
for precise event formats. properties:
items: auth_chain:
type: object type: array
title: PDU description: |-
properties: {} The [PDUs](/server-server-api/#pdus) forming the auth chain
example: of the given event. The event format varies depending on the
$ref: "examples/minimal_pdu.json" room version - check the [room version specification](/rooms)
required: ['auth_chain'] for precise event formats.
items:
type: object
title: PDU
properties: {}
example:
$ref: examples/minimal_pdu.json
required:
- auth_chain
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,84 +11,80 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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.
schema: content:
type: object application/json:
properties: schema:
auth_chain: type: object
type: array properties:
description: |- auth_chain:
The full set of authorization events that make up the state type: array
of the room, and their authorization events, recursively. Note that description: |-
events have a different format depending on the room version - The full set of authorization events that make up the state
check the [room version specification](/rooms) for precise event formats. of the room, and their authorization events, recursively. Note that
items: events have a different format depending on the room version -
type: object check the [room version specification](/rooms) for precise event formats.
title: PDU items:
description: |- type: object
The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format title: PDU
varies depending on the room version - check the [room version specification](/rooms) description: |-
for precise event formats. The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
properties: {} varies depending on the room version - check the [room version specification](/rooms)
example: for precise event formats.
$ref: "examples/minimal_pdu.json" properties: {}
pdus: example:
type: array $ref: examples/minimal_pdu.json
description: |- pdus:
The fully resolved state of the room at the given event. Note that type: array
events have a different format depending on the room version - description: |-
check the [room version specification](/rooms) for precise event formats. The fully resolved state of the room at the given event. Note that
items: events have a different format depending on the room version -
type: object check the [room version specification](/rooms) for precise event formats.
title: PDU items:
description: |- type: object
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format title: PDU
varies depending on the room version - check the [room version specification](/rooms) description: |-
for precise event formats. The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format
properties: {} varies depending on the room version - check the [room version specification](/rooms)
example: for precise event formats.
$ref: "examples/minimal_pdu.json" properties: {}
required: ['auth_chain', 'pdus'] example:
$ref: examples/minimal_pdu.json
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,72 +98,84 @@ 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.
schema: content:
type: object application/json:
properties: schema:
auth_chain_ids: type: object
type: array properties:
description: |- auth_chain_ids:
The full set of authorization events that make up the state type: array
of the room, and their authorization events, recursively. description: |-
items: The full set of authorization events that make up the state
type: string of the room, and their authorization events, recursively.
example: ["$an_event:example.org"] items:
pdu_ids: type: string
type: array example:
description: |- - $an_event:example.org
The fully resolved state of the room at the given event. pdu_ids:
items: type: array
type: string description: The fully resolved state of the room at the given event.
example: ["$an_event:example.org"] items:
required: ['auth_chain_ids', 'pdu_ids'] type: string
404: example:
- $an_event:example.org
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.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" $ref: ../client-server/definitions/errors/error.yaml
} examples:
schema: response:
"$ref": "../client-server/definitions/errors/error.yaml" value: {
"errcode": "M_NOT_FOUND",
"error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
}
"/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:
schema: application/json:
type: object schema:
properties: type: object
event_id: properties:
type: string event_id:
description: |- type: string
The ID of the event found description: 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
examples: - origin_server_ts
application/json: { examples:
"event_id": "$143273582443PhrSn:example.org", response:
"origin_server_ts": 1432735824653 value: {
} "event_id": "$143273582443PhrSn:example.org",
404: "origin_server_ts": 1432735824653
description: |- }
No event was found. "404":
examples: description: No event was found.
application/json: { content:
"errcode": "M_NOT_FOUND", application/json:
"error": "Unable to find event from 1432684800000 in forward direction" schema:
} $ref: ../client-server/definitions/errors/error.yaml
schema: examples:
"$ref": "../client-server/definitions/errors/error.yaml" response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unable to find event from 1432684800000 in forward direction"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,134 +38,160 @@ 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
name: body
type: object
required: true
schema: schema:
allOf: type: string
- $ref: "definitions/invite_event.yaml" requestBody:
- type: object content:
properties: application/json:
unsigned: schema:
type: object allOf:
title: UnsignedData - $ref: definitions/invite_event.yaml
description: |- - type: object
Information included alongside the event that is not signed. May include more properties:
than what is listed here. unsigned:
properties: type: object
invite_room_state: title: UnsignedData
type: array description: |-
description: |- Information included alongside the event that is not signed. May include more
An optional list of [stripped state events](/client-server-api/#stripped-state) than what is listed here.
to help the receiver of the invite identify the room. properties:
items: invite_room_state:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" type: array
example: description: |-
$ref: "../../event-schemas/examples/invite_room_state.json" An optional list of [stripped state events](/client-server-api/#stripped-state)
example: { to help the receiver of the invite identify the room.
"room_id": "!somewhere:example.org", items:
"type": "m.room.member", $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
"state_key": "@joe:elsewhere.com", example:
"origin": "example.org", $ref: ../../event-schemas/examples/invite_room_state.json
"origin_server_ts": 1549041175876, type: object
"sender": "@someone:example.org", example: {
"content": { "room_id": "!somewhere:example.org",
"membership": "invite" "type": "m.room.member",
}, "state_key": "@joe:elsewhere.com",
"signatures": { "origin": "example.org",
"example.com": { "origin_server_ts": 1549041175876,
"ed25519:key_version": "SomeSignatureHere" "sender": "@someone:example.org",
"content": {
"membership": "invite"
}, },
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
} }
} 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.
schema: content:
type: array application/json:
minItems: 2 schema:
maxItems: 2 type: array
items: minItems: 2
- type: integer maxItems: 2
description: The value `200`. items:
example: 200 anyOf:
- type: object - type: integer
description: An object containing the signed invite event. description: The value `200`.
title: Event Container example: 200
properties: - type: object
event: description: An object containing the signed invite event.
$ref: "definitions/invite_event.yaml" title: Event Container
required: ['event'] properties:
examples: event:
application/json: [ $ref: definitions/invite_event.yaml
200, required:
{ - event
"event": { examples:
"room_id": "!somewhere:example.org", response:
"type": "m.room.member", value: [
"state_key": "@someone:example.org", 200,
"origin": "example.org", {
"origin_server_ts": 1549041175876, "event": {
"sender": "@someone:example.org", "room_id": "!somewhere:example.org",
"unsigned": { "type": "m.room.member",
"invite_room_state": [ "state_key": "@someone:example.org",
{ "origin": "example.org",
"type": "m.room.name", "origin_server_ts": 1549041175876,
"sender": "@bob:example.org", "sender": "@someone:example.org",
"state_key": "", "unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": { "content": {
"name": "Example Room" "membership": "invite"
} },
}, "signatures": {
{ "example.com": {
"type": "m.room.join_rules", "ed25519:key_version": "SomeSignatureHere"
"sender": "@bob:example.org", },
"state_key": "", "elsewhere.com": {
"content": { "ed25519:k3y_versi0n": "SomeOtherSignatureHere"
"join_rule": "invite" }
} }
} }
]
},
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
} }
} ]
} "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.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_FORBIDDEN", examples:
"error": "User cannot invite the target user." response:
} value: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,101 +42,51 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: string
properties: requestBody:
room_version: content:
type: string application/json:
description: The version of the room where the user is being invited to. schema:
example: "2" type: object
event: properties:
$ref: "definitions/invite_event.yaml" room_version:
invite_room_state: type: string
type: array description: The version of the room where the user is being invited to.
description: |- example: "2"
An optional list of [stripped state events](/client-server-api/#stripped-state) event:
to help the receiver of the invite identify the room. $ref: definitions/invite_event.yaml
items: invite_room_state:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" type: array
example: description: |-
$ref: "../../event-schemas/examples/invite_room_state.json" An optional list of [stripped state events](/client-server-api/#stripped-state)
required: ['room_version', 'event'] to help the receiver of the invite identify the room.
example: { items:
"room_version": "2", $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
"event": { example:
"room_id": "!somewhere:example.org", $ref: ../../event-schemas/examples/invite_room_state.json
"type": "m.room.member", required:
"state_key": "@joe:elsewhere.com", - room_version
"origin": "example.org", - event
"origin_server_ts": 1549041175876, example: {
"sender": "@someone:example.org", "room_version": "2",
"content": { "event": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
}
responses:
200:
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched. Note that events have a different format depending on the
room version - check the [room version specification](/rooms) for precise event formats.
schema:
type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
examples:
application/json: {
"event": {
"room_id": "!somewhere:example.org", "room_id": "!somewhere:example.org",
"type": "m.room.member", "type": "m.room.member",
"state_key": "@someone:example.org", "state_key": "@joe:elsewhere.com",
"origin": "example.org", "origin": "example.org",
"origin_server_ts": 1549041175876, "origin_server_ts": 1549041175876,
"sender": "@someone:example.org", "sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": { "content": {
"membership": "invite" "membership": "invite"
}, },
@ -155,27 +94,71 @@ paths:
"example.com": { "example.com": {
"ed25519:key_version": "SomeSignatureHere" "ed25519:key_version": "SomeSignatureHere"
}, },
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
} }
} }
} }
403: required: true
responses:
"200":
description: |- description: |-
The invite is not allowed. This could be for a number of reasons, including: 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
* The sender is not allowed to send invites to the target user/homeserver. room version - check the [room version specification](/rooms) for precise event formats.
* The homeserver does not permit anyone to invite its users. content:
* The homeserver refuses to participate in the room. application/json:
schema: schema:
$ref: "../client-server/definitions/errors/error.yaml" type: object
examples: description: An object containing the signed invite event.
application/json: { title: Event Container
"errcode": "M_FORBIDDEN", properties:
"error": "User cannot invite the target user." event:
} $ref: definitions/invite_event.yaml
400: required:
- event
examples:
response:
value: {
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
},
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
}
"400":
description: |- 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,19 +166,54 @@ 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.
schema: content:
allOf: application/json:
- $ref: "../client-server/definitions/errors/error.yaml" schema:
- type: object allOf:
properties: - $ref: ../client-server/definitions/errors/error.yaml
room_version: - type: object
type: string properties:
description: |- room_version:
The version of the room. Required if the `errcode` type: string
is `M_INCOMPATIBLE_ROOM_VERSION`. description: |-
examples: The version of the room. Required if the `errcode`
application/json: { is `M_INCOMPATIBLE_ROOM_VERSION`.
"errcode": "M_INCOMPATIBLE_ROOM_VERSION", examples:
"error": "Your homeserver does not support the features required to join this room", response:
"room_version": "3" value: {
} "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
"403":
description: |-
The invite is not allowed. This could be for a number of reasons, including:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,118 +29,128 @@ 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.**
schema: content:
type: object application/json:
properties: schema:
room_version:
type: string
description: |-
The version of the room where the server is trying to join. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object type: object
title: Event Template
properties: properties:
sender: room_version:
type: string type: string
description: The user ID of the joining member. description: |-
example: "@someone:example.org" The version of the room where the server is trying to join. If not provided,
origin: the room version is assumed to be either "1" or "2".
type: string example: "2"
description: The name of the resident homeserver. event:
example: "matrix.org" description: |-
origin_server_ts: An unsigned template event. Note that events have a different format
type: integer depending on the room version - check the [room version specification](/rooms)
format: int64 for precise event formats.
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object type: object
title: Membership Event Content title: Event Template
description: The content of the event.
example: {"membership": "join"}
properties: properties:
membership: sender:
type: string type: string
description: The value `join`. description: The user ID of the joining member.
example: "join" example: "@someone:example.org"
join_authorised_via_users_server: origin:
type: string type: string
x-addedInMatrixVersion: "1.2" description: The name of the resident homeserver.
description: |- example: matrix.org
Required if the room is [restricted](/client-server-api/#restricted-rooms) origin_server_ts:
and is joining through one of the conditions available. If the type: integer
user is responding to an invite, this is not required. format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in An arbitrary user ID belonging to the resident server in
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:
required: - membership
- state_key required:
- origin - state_key
- origin_server_ts - origin
- type - origin_server_ts
- content - type
- sender - content
examples: - sender
application/json: { examples:
"room_version": "2", response:
"event": { value: {
"room_id": "!somewhere:example.org", "room_version": "2",
"type": "m.room.member", "event": {
"state_key": "@someone:example.org", "room_id": "!somewhere:example.org",
"origin": "example.org", "type": "m.room.member",
"origin_server_ts": 1549041175876, "state_key": "@someone:example.org",
"sender": "@someone:example.org", "origin": "example.org",
"content": { "origin_server_ts": 1549041175876,
"membership": "join", "sender": "@someone:example.org",
"join_authorised_via_users_server": "@anyone:resident.example.org" "content": {
} "membership": "join",
} "join_authorised_via_users_server": "@anyone:resident.example.org"
} }
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,45 +176,53 @@ 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.
schema: content:
allOf: application/json:
- $ref: "../client-server/definitions/errors/error.yaml" schema:
- type: object allOf:
properties: - $ref: ../client-server/definitions/errors/error.yaml
room_version: - type: object
type: string properties:
description: |- room_version:
The version of the room. Required if the `errcode` type: string
is `M_INCOMPATIBLE_ROOM_VERSION`. description: |-
examples: The version of the room. Required if the `errcode`
application/json: { is `M_INCOMPATIBLE_ROOM_VERSION`.
"errcode": "M_INCOMPATIBLE_ROOM_VERSION", examples:
"error": "Your homeserver does not support the features required to join this room", response:
"room_version": "3" value: {
} "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
403: "error": "Your homeserver does not support the features required to join this room",
schema: "room_version": "3"
$ref: "../client-server/definitions/errors/error.yaml" }
"403":
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", schema:
"error": "You are not invited to this room", $ref: ../client-server/definitions/errors/error.yaml
} examples:
404: response:
schema: value: {
$ref: "../client-server/definitions/errors/error.yaml" "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.
examples: content:
application/json: { application/json:
"errcode": "M_NOT_FOUND", schema:
"error": "Unknown room", $ref: ../client-server/definitions/errors/error.yaml
} examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
"/send_join/{roomId}/{eventId}": "/send_join/{roomId}/{eventId}":
put: put:
deprecated: true deprecated: true
@ -237,150 +244,167 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: string
properties: requestBody:
sender: content:
type: string application/json:
description: The user ID of the joining member. schema:
example: "@someone:example.org" type: object
origin: properties:
type: string sender:
description: The name of the joining homeserver. type: string
example: "matrix.org" description: The user ID of the joining member.
origin_server_ts: example: "@someone:example.org"
type: integer origin:
format: int64 type: string
description: A timestamp added by the joining homeserver. description: The name of the joining homeserver.
example: 1234567890 example: matrix.org
type: origin_server_ts:
type: string type: integer
description: The value `m.room.member`. format: int64
example: "m.room.member" description: A timestamp added by the joining homeserver.
state_key: example: 1234567890
type: string type:
description: The user ID of the joining member. type: string
example: "@someone:example.org" description: The value `m.room.member`.
content: example: m.room.member
type: object state_key:
title: Membership Event Content type: string
description: The content of the event. description: The user ID of the joining member.
example: {"membership": "join"} example: "@someone:example.org"
properties: content:
membership: type: object
type: string title: Membership Event Content
description: The value `join`. description: The content of the event.
example: "join" example:
join_authorised_via_users_server: membership: join
type: string properties:
x-addedInMatrixVersion: "1.2" membership:
description: |- type: string
Required if the room is [restricted](/client-server-api/#restricted-rooms) description: The value `join`.
and is joining through one of the conditions available. If the example: join
user is responding to an invite, this is not required. join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in An arbitrary user ID belonging to the resident server in
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.
The resident server which owns the provided user ID must have a The resident server which owns the provided user ID must have a
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:
required: - membership
- state_key required:
- sender - state_key
- origin - sender
- origin_server_ts - origin
- type - origin_server_ts
- content - type
example: { - content
"room_id": "!somewhere:example.org", required: true
"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:
schema: application/json:
type: array schema:
minItems: 2 type: array
maxItems: 2 minItems: 2
items: maxItems: 2
- type: integer items:
description: The value `200`. anyOf:
example: 200 - type: integer
- type: object description: The value `200`.
title: Room State example: 200
description: The state for the room. - type: object
properties: title: Room State
origin: description: The state for the room.
type: string properties:
description: The resident server's DNS name. origin:
auth_chain: type: string
type: array description: The resident server's DNS name.
description: |- auth_chain:
The auth chain for the entire current room state prior to the join event. type: array
description: |-
The auth chain for the entire current room state prior to the join event.
Note that events have a different format depending on the room version - check the Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats. [room version specification](/rooms) for precise event formats.
items: items:
type: object type: object
title: PDU title: PDU
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: state:
type: object type: array
properties: {} description: |-
state: The resolved current room state prior to the join event.
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the [room version specification](/rooms) The event format varies depending on the room version - check the [room version specification](/rooms)
for precise event formats. for precise event formats.
items: items:
type: object type: object
title: PDU title: PDU
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:
200, value: [
{ 200,
"origin": "matrix.org", {
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}], "origin": "matrix.org",
"state": [{"$ref": "examples/minimal_pdu.json"}], "auth_chain": [
"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

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,83 +73,180 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: boolean
properties: requestBody:
sender: content:
type: string application/json:
description: The user ID of the joining member. schema:
example: "@someone:example.org" type: object
origin: properties:
type: string sender:
description: The name of the joining homeserver. type: string
example: "matrix.org" description: The user ID of the joining member.
origin_server_ts: example: "@someone:example.org"
type: integer origin:
format: int64 type: string
description: A timestamp added by the joining homeserver. description: The name of the joining homeserver.
example: 1234567890 example: matrix.org
type: origin_server_ts:
type: string type: integer
description: The value `m.room.member`. format: int64
example: "m.room.member" description: A timestamp added by the joining homeserver.
state_key: example: 1234567890
type: string type:
description: The user ID of the joining member. type: string
example: "@someone:example.org" description: The value `m.room.member`.
content: example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
the room being joined that is able to issue invites to other
users. This is used in later validation of the auth rules for
the `m.room.member` event.
The resident server which owns the provided user ID must have a
valid signature on the event. If the resident server is receiving
the `/send_join` request, the signature must be added before sending
or persisting the event to other servers.
required:
- membership
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join",
"join_authorised_via_users_server": "@anyone:resident.example.org"
}
}
required: true
responses:
"200":
description: The join event has been accepted into the room.
content:
application/json:
schema:
type: object type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties: properties:
membership: origin:
type: string
description: The value `join`.
example: "join"
join_authorised_via_users_server:
type: string type: string
description: The resident server's DNS name.
members_omitted:
type: boolean
description: "`true` if `m.room.member` events have been omitted from `state`."
x-addedInMatrixVersion: "1.6"
auth_chain:
type: array
description: |-
All events in the auth chain for the new join event, as well
as those in the auth chains for any events returned in
`state`.
If the `omit_members` query parameter was set to `true`, then
any events that are returned in `state` may be omitted from
`auth_chain`, whether or not membership events are omitted
from `state`.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
`state`, and to allow elision of redundant events.
state:
type: array
description: |-
The resolved current room state prior to the join event.
If the request had `omit_members` set to `true`, events of
type `m.room.member` may be omitted from the response to
reduce the size of the response. If this is done,
`members_omitted` must be set to `true`.
items:
type: object
title: PDU
x-changedInMatrixVersion:
"1.6": permit omission of membership events.
event:
type: object
title: SignedMembershipEvent
x-addedInMatrixVersion: "1.2" x-addedInMatrixVersion: "1.2"
description: |- description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms) Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed
and is joining through one of the conditions available. If the copy of the membership event sent to other servers by the resident server, including the resident
user is responding to an invite, this is not required. server's signature.
servers_in_room:
type: array
x-addedInMatrixVersion: "1.6"
description: |-
**Required** if `members_omitted` is true.
An arbitrary user ID belonging to the resident server in A list of the servers active in the room (ie, those with joined members) before the join.
the room being joined that is able to issue invites to other items:
users. This is used in later validation of the auth rules for type: string
the `m.room.member` event. required:
- auth_chain
The resident server which owns the provided user ID must have a - state
valid signature on the event. If the resident server is receiving - origin
the `/send_join` request, the signature must be added before sending examples:
or persisting the event to other servers. response:
required: ['membership'] value: {
required: "origin": "matrix.org",
- state_key "auth_chain": [
- sender {
- origin "$ref": "examples/minimal_pdu.json"
- origin_server_ts }
- type ],
- content "state": [
example: { {
"room_id": "!somewhere:example.org", "$ref": "examples/minimal_pdu.json"
"type": "m.room.member", }
"state_key": "@someone:example.org", ],
"origin": "example.org", "event": {
"origin_server_ts": 1549041175876, "$ref": "examples/pdu_v4_join_membership.json"
"sender": "@someone:example.org", },
"content": { "members_omitted": true,
"membership": "join", "servers_in_room": [
"join_authorised_via_users_server": "@anyone:resident.example.org" "matrix.org",
} "example.com"
} ]
responses: }
400: "400":
description: |- description: |-
The request is invalid in some way. The request is invalid in some way.
@ -182,103 +269,42 @@ 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.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_UNABLE_TO_GRANT_JOIN", examples:
"error": "This server cannot send invites to you." response:
} value: {
403: "errcode": "M_UNABLE_TO_GRANT_JOIN",
schema: "error": "This server cannot send invites to you."
$ref: "../client-server/definitions/errors/error.yaml" }
"403":
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", schema:
"error": "You are not invited to this room", $ref: ../client-server/definitions/errors/error.yaml
} examples:
200: response:
description: |- value: {
The join event has been accepted into the room. "errcode": "M_FORBIDDEN",
schema: "error": "You are not invited to this room"
type: object }
properties: servers:
origin: - url: "{protocol}://{hostname}{basePath}"
type: string variables:
description: The resident server's DNS name. protocol:
members_omitted: enum:
type: boolean - http
description: "`true` if `m.room.member` events have been omitted from `state`." - https
x-addedInMatrixVersion: "1.6" default: https
auth_chain: hostname:
type: array default: localhost:8448
description: |- basePath:
All events in the auth chain for the new join event, as well default: /_matrix/federation/v2
as those in the auth chains for any events returned in components:
`state`. securitySchemes:
$ref: definitions/security.yaml
If the `omit_members` query parameter was set to `true`, then
any events that are returned in `state` may be omitted from
`auth_chain`, whether or not membership events are omitted
from `state`.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
reworded to include only consider state events returned in
`state`, and to allow elision of redundant events.
state:
type: array
description: |-
The resolved current room state prior to the join event.
If the request had `omit_members` set to `true`, events of
type `m.room.member` may be omitted from the response to
reduce the size of the response. If this is done,
`members_omitted` must be set to `true`.
items:
type: object
title: PDU
schema:
type: object
properties: {}
x-changedInMatrixVersion:
"1.6": |-
permit omission of membership events.
event:
type: object
title: SignedMembershipEvent
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed
copy of the membership event sent to other servers by the resident server, including the resident
server's signature.
servers_in_room:
type: array
x-addedInMatrixVersion: "1.6"
description: |-
**Required** if `members_omitted` is true.
A list of the servers active in the room (ie, those with joined members) before the join.
items:
type: string
required: ["auth_chain", "state", "origin"]
examples:
application/json: {
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}],
"event": {"$ref": "examples/pdu_v4_join_membership.json"},
"members_omitted": true,
"servers_in_room": ["matrix.org", "example.com"]
}

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

@ -11,19 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,88 +26,106 @@ 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.
schema: content:
$ref: "definitions/keys_query_response.yaml" application/json:
"/query": schema:
$ref: definitions/keys_query_response.yaml
/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: {
"server_keys": { "server_keys": {
"example.org": { "example.org": {
"ed25519:abc123": { "ed25519:abc123": {
"minimum_valid_until_ts": 1234567890 "minimum_valid_until_ts": 1234567890
}
} }
} }
} }
} properties:
properties: server_keys:
server_keys:
type: object
description: |-
The query criteria. The outer `string` key on the object is the
server name (eg: `matrix.org`). The inner `string` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty `server_keys`
array in the response.
The notary server may return multiple keys regardless of the Key IDs
given.
additionalProperties:
type: object type: object
name: ServerName description: |-
description: The server names to query. The query criteria. The outer `string` key on the object is the
server name (eg: `matrix.org`). The inner `string` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty `server_keys`
array in the response.
The notary server may return multiple keys regardless of the Key IDs
given.
additionalProperties: additionalProperties:
type: object type: object
title: Query Criteria description: The server names to query.
description: The server key IDs to query. additionalProperties:
properties: type: object
minimum_valid_until_ts: title: Query Criteria
type: integer description: The server key IDs to query.
format: int64 properties:
description: |- minimum_valid_until_ts:
A millisecond POSIX timestamp in milliseconds indicating when type: integer
the returned certificates will need to be valid until to be format: int64
useful to the requesting server. description: |-
A millisecond POSIX timestamp in milliseconds indicating when
the returned certificates will need to be valid until to be
useful to the requesting server.
If not supplied, the current time as determined by the notary 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.
schema: content:
$ref: "definitions/keys_query_response.yaml" application/json:
schema:
$ref: definitions/keys_query_response.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/key/v2

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

@ -11,19 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
schema: content:
$ref: "definitions/keys.yaml" application/json:
schema:
$ref: definitions/keys.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/key/v2

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

@ -11,21 +11,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,107 +29,115 @@ 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"
- 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.
The room versions the sending server has support for.
required: true # knocking was supported in v7 required: true # knocking was supported in v7
x-example: ["1", "7"] example:
- "1"
- "7"
schema:
type: array
items:
type: string
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.**
schema: content:
type: object application/json:
properties: schema:
room_version:
type: string
description: |-
The version of the room where the server is trying to knock.
example: "7"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object type: object
title: Event Template
properties: properties:
sender: room_version:
type: string type: string
description: The user ID of the knocking member. description: The version of the room where the server is trying to knock.
example: "@someone:example.org" example: "7"
origin: event:
type: string description: |-
description: The name of the resident homeserver. An unsigned template event. Note that events have a different format
example: "matrix.org" depending on the room version - check the [room version specification](/rooms)
origin_server_ts: for precise event formats.
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
type: object type: object
title: Membership Event Content title: Event Template
description: The content of the event.
example: {"membership": "knock"}
properties: properties:
membership: sender:
type: string type: string
description: The value `knock`. description: The user ID of the knocking member.
example: "knock" example: "@someone:example.org"
required: ['membership'] origin:
type: string
description: The name of the resident homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the knocking member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: knock
properties:
membership:
type: string
description: The value `knock`.
example: knock
required:
- membership
required:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
required: required:
- state_key - room_version # knocking was added in v7
- origin - event
- origin_server_ts examples:
- type response:
- content value: {
- sender "room_version": "7",
required: "event": {
- room_version # knocking was added in v7 "room_id": "!somewhere:example.org",
- event "type": "m.room.member",
examples: "state_key": "@someone:example.org",
application/json: { "origin": "example.org",
"room_version": "7", "origin_server_ts": 1549041175876,
"event": { "sender": "@someone:example.org",
"room_id": "!somewhere:example.org", "content": {
"type": "m.room.member", "membership": "knock"
"state_key": "@someone:example.org", }
"origin": "example.org", }
"origin_server_ts": 1549041175876, }
"sender": "@someone:example.org", "400":
"content": {
"membership": "knock"
}
}
}
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,47 +145,55 @@ 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.
schema: content:
allOf: application/json:
- $ref: "../client-server/definitions/errors/error.yaml" schema:
- type: object allOf:
properties: - $ref: ../client-server/definitions/errors/error.yaml
room_version: - type: object
type: string properties:
description: |- room_version:
The version of the room. Required if the `errcode` type: string
is `M_INCOMPATIBLE_ROOM_VERSION`. description: |-
examples: The version of the room. Required if the `errcode`
application/json: { is `M_INCOMPATIBLE_ROOM_VERSION`.
"errcode": "M_INCOMPATIBLE_ROOM_VERSION", examples:
"error": "Your homeserver does not support the features required to knock on this room", response:
"room_version": "7" value: {
} "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
404: "error": "Your homeserver does not support the features required to knock on this room",
description: |- "room_version": "7"
The room that the knocking server is attempting to knock upon is unknown }
to the receiving server. "403":
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.
schema: content:
allOf: application/json:
- $ref: "../client-server/definitions/errors/error.yaml" schema:
examples: allOf:
application/json: { - $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_FORBIDDEN", examples:
"error": "You are not permitted to knock on this room", response:
} value: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room"
}
"404":
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
"/send_knock/{roomId}/{eventId}": "/send_knock/{roomId}/{eventId}":
put: put:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
@ -207,117 +212,147 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: string
properties: requestBody:
sender: content:
type: string application/json:
description: The user ID of the knocking member. schema:
example: "@someone:example.org" type: object
origin: properties:
type: string sender:
description: The name of the knocking homeserver. type: string
example: "matrix.org" description: The user ID of the knocking member.
origin_server_ts: example: "@someone:example.org"
type: integer origin:
format: int64 type: string
description: A timestamp added by the knocking homeserver. description: The name of the knocking homeserver.
example: 1234567890 example: matrix.org
type: origin_server_ts:
type: string type: integer
description: The value `m.room.member`. format: int64
example: "m.room.member" description: A timestamp added by the knocking homeserver.
state_key: example: 1234567890
type: string type:
description: The user ID of the knocking member. type: string
example: "@someone:example.org" description: The value `m.room.member`.
content: example: m.room.member
type: object state_key:
title: Membership Event Content type: string
description: The content of the event. description: The user ID of the knocking member.
example: {"membership": "knock"} example: "@someone:example.org"
properties: content:
membership: type: object
type: string title: Membership Event Content
description: The value `knock`. description: The content of the event.
example: "knock" example:
required: ['membership'] membership: knock
required: properties:
- state_key membership:
- sender type: string
- origin description: The value `knock`.
- origin_server_ts example: knock
- type required:
- content - membership
example: { required:
"room_id": "!somewhere:example.org", - state_key
"type": "m.room.member", - sender
"state_key": "@someone:example.org", - origin
"origin": "example.org", - origin_server_ts
"origin_server_ts": 1549041175876, - type
"sender": "@someone:example.org", - content
"content": { example: {
"membership": "knock" "room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "knock"
}
} }
} required: true
responses: 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.
schema: content:
type: object application/json:
properties: schema:
knock_room_state: type: object
type: array properties:
items: knock_room_state:
$ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" type: array
description: |- items:
A list of [stripped state events](/client-server-api/#stripped-state) $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
to help the initiator of the knock identify the room. description: |-
example: A list of [stripped state events](/client-server-api/#stripped-state)
$ref: "../../event-schemas/examples/knock_room_state.json" to help the initiator of the knock identify the room.
required: ['knock_room_state'] example:
examples: $ref: ../../event-schemas/examples/knock_room_state.json
application/json: { required:
"knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"} - knock_room_state
} examples:
404: response:
description: |- value: {
The room that the knocking server is attempting to knock upon is unknown "knock_room_state": {
to the receiving server. "$ref": "../../event-schemas/examples/knock_room_state.json"
schema: }
allOf: }
- $ref: "../client-server/definitions/errors/error.yaml" "403":
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.
schema: content:
allOf: application/json:
- $ref: "../client-server/definitions/errors/error.yaml" schema:
examples: allOf:
application/json: { - $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_FORBIDDEN", examples:
"error": "You are not permitted to knock on this room", response:
} value: {
"errcode": "M_FORBIDDEN",
"error": "You are not permitted to knock on this room"
}
"404":
description: |-
The room that the knocking server is attempting to knock upon is unknown
to the receiving server.
content:
application/json:
schema:
allOf:
- $ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,105 +29,115 @@ 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.**
schema: content:
type: object application/json:
properties: schema:
room_version:
type: string
description: |-
The version of the room where the server is trying to leave. If not provided,
the room version is assumed to be either "1" or "2".
example: "2"
event:
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the [room version specification](/rooms)
for precise event formats.
type: object type: object
title: Event Template
properties: properties:
sender: room_version:
type: string type: string
description: The user ID of the leaving member. description: |-
example: "@someone:example.org" The version of the room where the server is trying to leave. If not provided,
origin: the room version is assumed to be either "1" or "2".
type: string example: "2"
description: The name of the resident homeserver. event:
example: "matrix.org" description: |-
origin_server_ts: An unsigned template event. Note that events have a different format
type: integer depending on the room version - check the [room version specification](/rooms)
format: int64 for precise event formats.
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object type: object
title: Membership Event Content title: Event Template
description: The content of the event.
example: {"membership": "leave"}
properties: properties:
membership: sender:
type: string type: string
description: The value `leave`. description: The user ID of the leaving member.
example: "leave" example: "@someone:example.org"
required: ['membership'] origin:
required: type: string
- state_key description: The name of the resident homeserver.
- sender example: matrix.org
- origin origin_server_ts:
- origin_server_ts type: integer
- type format: int64
- content description: A timestamp added by the resident homeserver.
examples: example: 1234567890
application/json: { type:
"room_version": "2", type: string
"event": { description: The value `m.room.member`.
"room_id": "!somewhere:example.org", example: m.room.member
"type": "m.room.member", state_key:
"state_key": "@someone:example.org", type: string
"origin": "example.org", description: The user ID of the leaving member.
"origin_server_ts": 1549041175876, example: "@someone:example.org"
"sender": "@someone:example.org", content:
"content": { type: object
"membership": "leave" title: Membership Event Content
} description: The content of the event.
} example:
} membership: leave
403: properties:
description: |- membership:
The request is not authorized. This could mean that the user is not in the room. type: string
schema: description: The value `leave`.
$ref: "../client-server/definitions/errors/error.yaml" example: leave
examples: required:
application/json: { - membership
"errcode": "M_FORBIDDEN", required:
"error": "User is not in the room." - state_key
} - sender
- origin
- origin_server_ts
- type
- content
examples:
response:
value: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
}
}
"403":
description: The request is not authorized. This could mean that the user is not
in the room.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "User is not in the room."
}
"/send_leave/{roomId}/{eventId}": "/send_leave/{roomId}/{eventId}":
put: put:
deprecated: true deprecated: true
@ -160,93 +159,108 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: string
properties: requestBody:
sender: content:
type: string application/json:
description: The user ID of the leaving member. schema:
example: "@someone:example.org" type: object
origin: properties:
type: string sender:
description: The name of the leaving homeserver. type: string
example: "matrix.org" description: The user ID of the leaving member.
origin_server_ts: example: "@someone:example.org"
type: integer origin:
format: int64 type: string
description: A timestamp added by the leaving homeserver. description: The name of the leaving homeserver.
example: 1234567890 example: matrix.org
type: origin_server_ts:
type: string type: integer
description: The value `m.room.member`. format: int64
example: "m.room.member" description: A timestamp added by the leaving homeserver.
state_key: example: 1234567890
type: string type:
description: The user ID of the leaving member. type: string
example: "@someone:example.org" description: The value `m.room.member`.
content: example: m.room.member
type: object state_key:
title: Membership Event Content type: string
description: The content of the event. description: The user ID of the leaving member.
example: {"membership": "leave"} example: "@someone:example.org"
properties: content:
membership: type: object
type: string title: Membership Event Content
description: The value `leave`. description: The content of the event.
example: "leave" example:
required: ['membership'] membership: leave
depth: properties:
type: integer membership:
description: This field must be present but is ignored; it may be 0. type: string
example: 12 description: The value `leave`.
required: example: leave
- state_key required:
- sender - membership
- origin depth:
- origin_server_ts type: integer
- type description: This field must be present but is ignored; it may be 0.
- depth example: 12
- content required:
example: { - state_key
"room_id": "!somewhere:example.org", - sender
"type": "m.room.member", - origin
"state_key": "@someone:example.org", - origin_server_ts
"origin": "example.org", - type
"origin_server_ts": 1549041175876, - depth
"sender": "@someone:example.org", - content
"content": { required: true
"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.
schema: content:
type: array application/json:
minItems: 2 schema:
maxItems: 2 type: array
items: minItems: 2
- type: integer maxItems: 2
description: The value `200`. items:
example: 200 anyOf:
- type: object - type: integer
title: Empty Object description: The value `200`.
description: An empty object. example: 200
examples: - type: object
application/json: [200, {}] title: Empty Object
description: An empty object.
examples:
response:
value: [
200,
{}
]
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,21 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,86 +44,108 @@ 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
name: body
type: object
required: true
schema: schema:
type: object type: string
properties: requestBody:
sender: content:
type: string application/json:
description: The user ID of the leaving member. schema:
example: "@someone:example.org" type: object
origin: properties:
type: string sender:
description: The name of the leaving homeserver. type: string
example: "matrix.org" description: The user ID of the leaving member.
origin_server_ts: example: "@someone:example.org"
type: integer origin:
format: int64 type: string
description: A timestamp added by the leaving homeserver. description: The name of the leaving homeserver.
example: 1234567890 example: matrix.org
type: origin_server_ts:
type: string type: integer
description: The value `m.room.member`. format: int64
example: "m.room.member" description: A timestamp added by the leaving homeserver.
state_key: example: 1234567890
type: string type:
description: The user ID of the leaving member. type: string
example: "@someone:example.org" description: The value `m.room.member`.
content: example: m.room.member
type: object state_key:
title: Membership Event Content type: string
description: The content of the event. description: The user ID of the leaving member.
example: {"membership": "leave"} example: "@someone:example.org"
properties: content:
membership: type: object
type: string title: Membership Event Content
description: The value `leave`. description: The content of the event.
example: "leave" example:
required: ['membership'] membership: leave
depth: properties:
type: integer membership:
description: This field must be present but is ignored; it may be 0. type: string
example: 12 description: The value `leave`.
required: example: leave
- state_key required:
- sender - membership
- origin depth:
- origin_server_ts type: integer
- type description: This field must be present but is ignored; it may be 0.
- depth example: 12
- content required:
example: { - state_key
"room_id": "!somewhere:example.org", - sender
"type": "m.room.member", - origin
"state_key": "@someone:example.org", - origin_server_ts
"origin": "example.org", - type
"origin_server_ts": 1549041175876, - depth
"sender": "@someone:example.org", - content
"content": { example: {
"membership": "leave" "room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
} }
} required: true
responses: 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.
schema: content:
type: object application/json:
title: Empty Object schema:
description: An empty object. type: object
examples: title: Empty Object
application/json: {} description: An empty object.
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v2
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,19 +12,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,29 +28,46 @@ 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:
schema: application/json:
type: object schema:
properties: type: object
sub: properties:
type: string sub:
description: The Matrix User ID who generated the token. type: string
example: "@alice:example.com" description: The Matrix User ID who generated the token.
required: ['sub'] example: "@alice:example.com"
401: required:
- sub
"401":
description: The token was not recognized or has expired. description: The token was not recognized or has expired.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_UNKNOWN_TOKEN", examples:
"error": "Access token unknown or expired" response:
} value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Access token unknown or expired"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1

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

@ -11,21 +11,12 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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
type: integer description: The maximum number of rooms to return. Defaults to 0 (no limit).
description: |- example: 10
The maximum number of rooms to return. Defaults to 0 (no limit). schema:
x-example: 10 type: integer
- 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,32 +77,27 @@ paths:
operationId: queryPublicRooms operationId: queryPublicRooms
security: security:
- signedRequest: [] - signedRequest: []
parameters: requestBody:
- in: body content:
name: body application/json:
required: true schema:
description: |- type: object
Options for which rooms to return, or empty object to use defaults. properties:
schema: limit:
type: object type: integer
properties: description: Limit the number of results returned.
limit: since:
type: integer type: string
description: |- description: |-
Limit the number of results returned. A pagination token from a previous request, allowing servers
since: to get the next (or previous) batch of rooms. The direction
type: string of pagination is specified solely by which token is supplied,
description: |- rather than via an explicit flag.
A pagination token from a previous request, allowing servers filter:
to get the next (or previous) batch of rooms. The direction type: object
of pagination is specified solely by which token is supplied, title: Filter
rather than via an explicit flag. description: Filter to apply to the results.
filter: properties:
type: object
title: "Filter"
description: |-
Filter to apply to the results.
properties:
generic_search_term: generic_search_term:
type: string type: string
description: |- description: |-
@ -122,85 +113,109 @@ paths:
for. To include rooms without a room type, specify `null` within this for. To include rooms without a room type, specify `null` within this
list. When not specified, all applicable rooms (regardless of type) list. When not specified, all applicable rooms (regardless of type)
are returned. are returned.
include_all_networks: include_all_networks:
type: boolean type: boolean
description: |- description: |-
Whether or not to include all known networks/protocols from Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false. application services on the homeserver. Defaults to false.
example: false example: false
third_party_instance_id: third_party_instance_id:
type: string type: string
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,
"include_all_networks": false, "m.space"
"third_party_instance_id": "irc" ]
} },
"include_all_networks": false,
"third_party_instance_id": "irc"
}
description: Options for which rooms to return, or empty object to use defaults.
required: true
responses: responses:
200: "200":
description: A list of the rooms on the server. description: A list of the rooms on the server.
schema: content:
type: object application/json:
description: A list of the rooms on the server. schema:
required: ["chunk"] type: object
properties: description: A list of the rooms on the server.
chunk: required:
title: "PublicRoomsChunks" - chunk
type: array properties:
description: A paginated chunk of public rooms. chunk:
items: title: PublicRoomsChunks
allOf: type: array
- $ref: "../client-server/definitions/public_rooms_chunk.yaml" description: A paginated chunk of public rooms.
- type: object items:
properties: allOf:
# Override description of join_rule - $ref: ../client-server/definitions/public_rooms_chunk.yaml
join_rule: - type: object
type: string properties:
description: |- # Override description of join_rule
The room's join rule. When not present, the room is assumed to join_rule:
be `public`. Note that rooms with `invite` join rules are not type: string
expected here, but rooms with `knock` rules are given their description: |-
near-public nature. The room's join rule. When not present, the room is assumed to
next_batch: be `public`. Note that rooms with `invite` join rules are not
type: string expected here, but rooms with `knock` rules are given their
description: |- near-public nature.
A pagination token for the response. The absence of this token next_batch:
means there are no more results to fetch and the client should type: string
stop paginating. description: |-
prev_batch: A pagination token for the response. The absence of this token
type: string means there are no more results to fetch and the client should
description: |- stop paginating.
A pagination token that allows fetching previous results. The prev_batch:
absence of this token means there are no results before this type: string
batch, i.e. this is the first batch. description: |-
total_room_count_estimate: A pagination token that allows fetching previous results. The
type: integer absence of this token means there are no results before this
description: |- batch, i.e. this is the first batch.
An estimate on the total number of public rooms, if the total_room_count_estimate:
server has an estimate. type: integer
examples: description: |-
application/json: { An estimate on the total number of public rooms, if the
"chunk": [ server has an estimate.
{ examples:
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", response:
"guest_can_join": false, value: {
"name": "CHEESE", "chunk": [
"num_joined_members": 37, {
"room_id": "!ol19s:bleecker.street", "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
"topic": "Tasty tasty cheese", "guest_can_join": false,
"world_readable": true, "name": "CHEESE",
"join_rule": "public", "num_joined_members": 37,
"room_type": "m.space" "room_id": "!ol19s:bleecker.street",
} "topic": "Tasty tasty cheese",
], "world_readable": true,
"next_batch": "p190q", "join_rule": "public",
"prev_batch": "p1902", "room_type": "m.space"
"total_room_count_estimate": 115 }
} ],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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

@ -12,19 +12,10 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 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,50 +55,57 @@ 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.
schema: content:
type: object application/json:
properties: schema:
room_id: type: object
type: string properties:
description: The room ID mapped to the queried room alias. room_id:
x-example: "!roomid1234:example.org" type: string
servers: description: The room ID mapped to the queried room alias.
type: array example: "!roomid1234:example.org"
description: |- servers:
An array of server names that are likely to hold the given room. This type: array
list may or may not include the server answering the query. description: |-
items: An array of server names that are likely to hold the given room. This
type: string list may or may not include the server answering the query.
required: items:
- "room_id" type: string
- "servers" required:
examples: - room_id
application/json: { - servers
"room_id": "!roomid1234:example.org", examples:
"servers": [ response:
"example.org", value: {
"example.com", "room_id": "!roomid1234:example.org",
"another.example.com:8449", "servers": [
] "example.org",
} "example.com",
404: "another.example.com:8449"
]
}
"404":
description: The room alias was not found. description: The room alias was not found.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_NOT_FOUND", examples:
"error": "Room alias not found." response:
} value: {
"/query/profile": "errcode": "M_NOT_FOUND",
"error": "Room alias not found."
}
/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,32 +147,53 @@ 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`.
schema: content:
type: object application/json:
properties: schema:
displayname: type: object
type: string properties:
description: |- displayname:
The display name of the user. May be omitted if the user does not have a type: string
display name set. description: |-
x-example: "John Doe" The display name of the user. May be omitted if the user does not have a
avatar_url: display name set.
type: string example: John Doe
description: |- avatar_url:
The avatar URL for the user's avatar. May be omitted if the user does not type: string
have an avatar set. description: |-
x-example: "mxc://matrix.org/MyC00lAvatar" The avatar URL for the user's avatar. May be omitted if the user does not
examples: have an avatar set.
application/json: { example: mxc://matrix.org/MyC00lAvatar
"displayname": "John Doe", examples:
"avatar_url": "mxc://matrix.org/MyC00lAvatar" response:
} value: {
404: "displayname": "John Doe",
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
}
"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.
schema: content:
$ref: "../client-server/definitions/errors/error.yaml" application/json:
examples: schema:
application/json: { $ref: ../client-server/definitions/errors/error.yaml
"errcode": "M_NOT_FOUND", examples:
"error": "User does not exist." response:
} value: {
"errcode": "M_NOT_FOUND",
"error": "User does not exist."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8448
basePath:
default: /_matrix/federation/v1
components:
securitySchemes:
$ref: definitions/security.yaml

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