Merge remote-tracking branch 'matrix-org/master' into travis/c2s/3pid-binding

pull/1567/head
Travis Ralston 6 years ago
commit 86c85aea71

@ -23,9 +23,55 @@ buildswaggerui: &buildswaggerui
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
patch api/client-server/index.html swagger-ui.patch
checkexamples: &checkexamples
name: Check Event Examples
command: |
source /env/bin/activate
cd event-schemas
./check_examples.py
cd ../api
./check_examples.py
genmatrixassets: &genmatrixassets
name: Generate/Verify matrix.org assets
command: |
source /env/bin/activate
./scripts/generate-matrix-org-assets
validateapi: &validateapi
name: Validate OpenAPI specifications
command: |
cd api
npm install
node validator.js -s "client-server"
buildspeculator: &buildspeculator
name: Build Speculator
command: |
cd scripts/speculator
go build -v
buildcontinuserv: &buildcontinuserv
name: Build Continuserv
command: |
cd scripts/continuserv
go build -v
version: 2
jobs:
validate-docs:
docker:
- image: node:alpine
steps:
- checkout
- run: *validateapi
check-docs:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *checkexamples
- run: *genmatrixassets # We don't actually use the assets, but we do want to make sure they build
build-docs:
docker:
- image: uhoreg/matrix-doc-build
@ -37,7 +83,6 @@ jobs:
- run:
name: "Doc build is available at:"
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
build-swagger:
docker:
- image: uhoreg/matrix-doc-build
@ -50,6 +95,18 @@ jobs:
- run:
name: "Swagger UI is available at:"
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
build-dev-scripts:
docker:
- image: golang:1.8
steps:
- checkout
- run:
name: Install Dependencies
command: |
go get -v github.com/hashicorp/golang-lru
go get -v gopkg.in/fsnotify/fsnotify.v1
- run: *buildcontinuserv
- run: *buildspeculator
workflows:
version: 2
@ -58,6 +115,9 @@ workflows:
jobs:
- build-docs
- build-swagger
- check-docs
- validate-docs
- build-dev-scripts
notify:
webhooks:

@ -19,12 +19,14 @@ properties:
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: irc
example: "irc"
fields:
description: Information used to identify this third party location.
type: object
example:
"network": "freenode"
example: {
"network": "freenode",
"channel": "#matrix"
}
required: ['alias', 'protocol', 'fields']
title: Location
type: object

@ -11,41 +11,60 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Protocol
type: object
properties:
user_fields:
description: Fields used to identify a third party user.
description: |-
Fields which may be used to identify a third party user. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the nickname of a user.
type: array
items:
type: string
description: Field used to identify a third party user.
example: ["network", "nickname"]
location_fields:
description: Fields used to identify a third party location.
description: |-
Fields which may be used to identify a third party location. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the name of a channel.
type: array
items:
type: string
description: Field used to identify a third party location.
example: ["network", "channel"]
icon:
description: An icon representing the third party protocol.
description: A content URI representing an icon for the third party protocol.
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:
title: Field Types
description: All location or user fields should have an entry here.
description: |-
The type definitions for the fields defined in the ``user_fields`` and
``location_fields``. Each entry in those arrays MUST have an entry here. The
``string`` key for this object is field name itself.
May be an empty object if no fields are defined.
type: object
properties:
fieldname:
title: Field Type
description: Definition of valid values for a field.
type: object
properties:
regexp:
description: A regular expression for validation of a field's value.
type: string
placeholder:
description: An placeholder serving as a valid example of the field value.
type: string
additionalProperties:
title: Field Type
description: Definition of valid values for a field.
type: object
properties:
regexp:
description: |-
A regular expression for validation of a field's value. This may be relatively
coarse to verify the value as the application service providing this protocol
may apply additional validation or filtering.
type: string
placeholder:
description: An placeholder serving as a valid example of the field value.
type: string
required: ['regexp', 'placeholder']
required: ['fieldname']
example: {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
@ -63,17 +82,32 @@ properties:
instances:
description: |-
A list of objects representing independent instances of configuration.
For instance multiple networks on IRC if multiple are bridged by the
same bridge.
For example, multiple networks on IRC if multiple are provided by the
same application service.
type: array
items:
type: object
example: {
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
title: Protocol
type: object
title: Protocol Instance
properties:
desc:
type: string
description: A human-readable description for the protocol, such as the name.
example: "Freenode"
icon:
type: string
description: |-
An optional content URI representing the protocol. Overrides the one provided
at the higher level Protocol object.
example: "mxc://example.org/JkLmNoPq"
fields:
type: object
description: Preset values for ``fields`` the client may use to search by.
example: {
"network": "freenode"
}
network_id:
type: string
description: A unique identifier across all instances.
example: "freenode"
required: ['desc', 'fields', 'network_id']
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

@ -36,6 +36,7 @@ example: {
},
"instances": [
{
"network_id": "freenode",
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
@ -59,6 +60,7 @@ example: {
},
"instances": [
{
"network_id": "gitter",
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"fields": {}

@ -0,0 +1,18 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
homeserverAccessToken:
type: apiKey
description: The ``hs_token`` provided by the application service's registration.
name: access_token
in: query

@ -21,11 +21,13 @@ properties:
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: gitter
example: "gitter"
fields:
description: Information used to identify this third party location.
type: object
example:
example: {
"user": "jim"
}
required: ['userid', 'protocol', 'fields']
title: User
type: object

@ -1,4 +1,3 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
@ -20,83 +19,15 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events.
schema:
type: object
example: {
"events": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
description: "Transaction informations"
properties:
events:
type: array
description: A list of events
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
@ -104,6 +35,8 @@ paths:
with specific information about the various third party networks that
an application service supports.
operationId: getProtocolMetadata
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -143,7 +76,7 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}":
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
@ -151,6 +84,8 @@ paths:
User ID linked to a user on the third party network, given a set of
user parameters.
operationId: queryUserByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -196,12 +131,14 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}":
"/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portal rooms leading to a third party location.
summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -247,13 +184,15 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location":
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retreive an array of third party network locations from a Matrix room
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
- homeserverAccessToken: []
parameters:
- in: query
name: alias
@ -292,12 +231,14 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user":
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retreive 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
security:
- homeserverAccessToken: []
parameters:
- in: query
name: userid

@ -20,11 +20,13 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomAlias}":
get:
@ -36,6 +38,8 @@ paths:
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
operationId: queryRoomByAlias
security:
- homeserverAccessToken: []
parameters:
- in: path
name: roomAlias

@ -20,11 +20,13 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/users/{userId}":
get:
@ -36,6 +38,8 @@ paths:
send this request when it receives an event for an unknown user ID in
the application service's namespace, such as a room invite.
operationId: queryUserById
security:
- homeserverAccessToken: []
parameters:
- in: path
name: userId

@ -0,0 +1,78 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
security:
- homeserverAccessToken: []
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events.
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
]
}
description: Transaction information
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object

@ -105,7 +105,8 @@ paths:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: number
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string

@ -0,0 +1,88 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Application Service Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
paths:
"/directory/list/appservice/{networkId}/{roomId}":
put:
summary: |-
Updates a room's visibility in the application service's room directory.
description: |-
Updates the visibility of a given room on the application service's room
directory.
This API is similar to the room directory visibility API used by clients
to update the homeserver's more general room directory.
This API requires the use of an application service access token (``as_token``)
instead of a typical client's access_token. This API cannot be invoked by
users who are not identified as application services.
operationId: updateAppserviceRoomDirectoryVsibility
parameters:
- in: path
type: string
name: networkId
description: |-
The protocol (network) ID to update the room list for. This would
have been provided by the application service as being listed as
a supported protocol.
required: true
x-example: "irc"
- in: path
type: string
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:domain.com"
- in: body
name: body
required: true
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
description: The room's directory visibility has been updated.
schema:
type: object
examples:
application/json: {}
tags:
- Application service room directory management

@ -259,7 +259,8 @@ paths:
description: "The URL to get a preview of"
required: true
- in: query
type: number
type: integer
format: int64
x-example: 1510610716656
name: ts
description: |-
@ -276,7 +277,8 @@ paths:
type: object
properties:
"matrix:image:size":
type: number
type: integer
format: int64
description: |-
The byte-size of the image. Omitted if there is no image attached.
"og:image":
@ -324,7 +326,8 @@ paths:
type: object
properties:
m.upload.size:
type: number
type: integer
format: int64
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.

@ -11,7 +11,7 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Filter
title: EventFilter
properties:
limit:
description: The maximum number of events to return.

@ -45,7 +45,7 @@ properties:
description: |-
The name of the room, if any.
num_joined_members:
type: number
type: integer
description: |-
The number of members joined to the room.
room_id:
@ -82,7 +82,7 @@ properties:
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: number
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.

@ -13,23 +13,23 @@
# limitations under the License.
allOf:
- $ref: event_filter.yaml
title: RoomEventFilter
properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
filter.
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included.
items:
type: string
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a url key in their content. If
``false``, excludes those events.
type: object
- type: object
title: RoomEventFilter
properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
filter.
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included.
items:
type: string
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a ``url`` key in their content. If
``false``, excludes those events. Defaults to ``false``.

@ -11,6 +11,8 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Filter
properties:
event_fields:
description: List of event fields to include. If this list is absent then all
@ -40,6 +42,7 @@ properties:
room:
title: RoomFilter
description: Filters to be applied to room data.
type: object
properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
@ -76,5 +79,3 @@ properties:
allOf:
- $ref: room_event_filter.yaml
description: The per user account data to include for rooms.
type: object
type: object

@ -0,0 +1,24 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Homeserver Information
description: |-
Used by clients to discover homeserver information.
type: object
properties:
base_url:
type: string
description: The base URL for the homeserver for client-server connections.
example: https://matrix.example.com
required:
- base_url

@ -0,0 +1,24 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Identity Server Information
description: |-
Used by clients to discover identity server information.
type: object
properties:
base_url:
type: string
description: The base URL for the identity server for client-server connections.
example: https://identity.example.com
required:
- base_url

@ -41,7 +41,7 @@ paths:
required: true
x-example: "#monkeys:matrix.org"
- in: body
name: roomInfo
name: body
description: Information about this room alias.
required: true
schema:
@ -50,24 +50,24 @@ paths:
room_id:
type: string
description: The room ID to set.
required: ['room_id']
example: {
"room_id": "!abnjk1jdasj98:capuchins.com"
}
"room_id": "!abnjk1jdasj98:capuchins.com"
}
responses:
200:
description: The mapping was created.
examples:
application/json: {
}
application/json: {}
schema:
type: object
409:
description: A room alias with that name already exists.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:

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

@ -123,7 +123,7 @@ paths:
parameters:
- in: query
name: limit
type: number
type: integer
description: |-
Limit the number of results returned.
- in: query
@ -173,7 +173,7 @@ paths:
type: object
properties:
limit:
type: number
type: integer
description: |-
Limit the number of results returned.
since:
@ -194,8 +194,26 @@ paths:
description: |-
A string to search for in the room metadata, e.g. name,
topic, canonical alias etc. (Optional).
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
homeserver. Can only be used if ``include_all_networks`` is false.
example: "irc"
example: {
"limit": 10, "filter": {"generic_search_term": "foo"}}
"limit": 10,
"filter": {
"generic_search_term": "foo"
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
responses:
200:
description: A list of the rooms on the server.
@ -233,7 +251,7 @@ paths:
description: |-
The name of the room, if any.
num_joined_members:
type: number
type: integer
description: |-
The number of members joined to the room.
room_id:
@ -270,7 +288,7 @@ paths:
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: number
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.

@ -45,7 +45,7 @@ paths:
required: false
x-example: "xxxxx"
- in: query
type: number
type: integer
name: limit
description: Limit on the number of events to return in this request.
required: false

@ -343,6 +343,8 @@ paths:
This endpoint allows the creation, modification and deletion of pushers
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
When creating push rules, they MUST be enabled by default.
operationId: setPushRule
security:
- accessToken: []
@ -424,7 +426,7 @@ paths:
required: ["actions"]
responses:
200:
description: The pusher was set.
description: The push rule was created/updated.
examples:
application/json: {
}

@ -218,7 +218,7 @@ paths:
description: The email address
example: "example@example.com"
send_attempt:
type: number
type: integer
description: Used to distinguish protocol level retries from requests to re-send the email.
example: 1
required: ["client_secret", "email", "send_attempt"]
@ -283,7 +283,7 @@ paths:
description: The phone number.
example: "example@example.com"
send_attempt:
type: number
type: integer
description: Used to distinguish protocol level retries from requests to re-send the SMS message.
example: 1
required: ["client_secret", "country", "phone_number", "send_attempt"]

@ -87,6 +87,16 @@ paths:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
@ -142,5 +152,15 @@ paths:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation

@ -41,7 +41,7 @@ paths:
type: string
description: |-
The point to return events from. If given, this should be a
`next_batch` result from a previous call to this endpoint.
``next_batch`` result from a previous call to this endpoint.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
@ -95,6 +95,7 @@ paths:
# for now :/
description: |-
This takes a `filter`_.
$ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string
@ -179,7 +180,7 @@ paths:
description: Mapping of category name to search criteria.
properties:
count:
type: number
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array

@ -77,13 +77,14 @@ paths:
- in: query
name: set_presence
type: string
enum: ["offline"]
enum: ["offline", "online", "unavailable"]
description: |-
Controls whether the client is automatically marked as online by
polling this API. If this parameter is omitted then the client is
automatically marked as online when it uses this API. Otherwise if
the parameter is set to "offline" then the client is not marked as
being online when it uses this API.
being online when it uses this API. When set to "unavailable", the
client is marked as being idle.
x-example: "offline"
- in: query
name: timeout
@ -227,6 +228,14 @@ paths:
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

@ -73,7 +73,7 @@ paths:
$ref: definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portals rooms leading to a third party location.
summary: Retrieve Matrix-side portals rooms leading to a third party location.
description: |-
Requesting this endpoint with a valid protocol name results in a list
of successful mapping results in a JSON array. Each result contains
@ -151,7 +151,7 @@ paths:
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retreive an array of third party network locations from a Matrix room
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
@ -181,7 +181,7 @@ paths:
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retreive 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
security:
- accessToken: []

@ -47,7 +47,7 @@ paths:
description: The term to search for
example: "foo"
limit:
type: number
type: integer
description: The maximum number of results to return (Defaults to 10).
example: 10
required: ["search_term"]

@ -0,0 +1,66 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Server Discovery API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /.well-known
produces:
- application/json
paths:
"/matrix/client":
get:
summary: Gets Matrix server discovery information about the domain.
description: |-
Gets discovery information about the domain. The file may include
additional keys, which MUST follow the Java package naming convention,
e.g. ``com.example.myapp.property``. This ensures property names are
suitably namespaced for each application and reduces the risk of
clashes.
Note that this endpoint is not necessarily handled by the homeserver,
but by another webserver, to be used for discovering the homeserver URL.
operationId: getWellknown
responses:
200:
description: Server discovery information.
examples:
application/json: {
"m.homeserver": {
"base_url": "https://matrix.example.com"
},
"m.identity_server": {
"base_url": "https://identity.example.com"
}
}
schema:
type: object
properties:
m.homeserver:
description: Information about the homeserver to connect to.
"$ref": "definitions/wellknown/homeserver.yaml"
m.identity_server:
description: Optional. Information about the identity server to connect to.
"$ref": "definitions/wellknown/identity_server.yaml"
additionalProperties:
description: Application-dependent keys using Java package naming convention.
required:
- m.homeserver
404:
description: No server discovery information available.
tags:
- Server administration

@ -18,15 +18,17 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: A client can check whether ownership of a 3pid was validated
description: |-
Determines if a given 3pid has been validated by a user.
operationId: getValidated3pid
parameters:
- in: query
@ -46,10 +48,10 @@ paths:
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
schema:
type: object
properties:
@ -61,7 +63,10 @@ paths:
description: The address of the 3pid being looked up.
validated_at:
type: integer
description: Timestamp indicating the time that the 3pid was validated.
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
description: |-
The session has not been validated.
@ -71,16 +76,20 @@ paths:
``errcode`` will be ``M_SESSION_EXPIRED``.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
"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"
"/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
@ -90,7 +99,7 @@ paths:
Future calls to ``/lookup`` for any of the session\'s 3pids will return
this association.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -101,10 +110,10 @@ paths:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
properties:
sid:
type: string
@ -121,19 +130,18 @@ paths:
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"
}
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
schema:
type: object
properties:
@ -157,7 +165,19 @@ paths:
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
description: |-
The signatures of the verifying identity services which show that the
association should be trusted, if you trust the verifying identity
services.
$ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
400:
description: |-
The association was not published.
@ -167,13 +187,17 @@ paths:
``errcode`` will be ``M_SESSION_EXPIRED``.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
"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"

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -34,13 +35,13 @@ paths:
that that user was able to read the email for that email address, and
so we validate ownership of the email address.
Note that Home Servers offer APIs that proxy this API, adding
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/email/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the email
address given is already registered on the server.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -51,14 +52,14 @@ paths:
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt
description: A unique string used to identify the validation attempt.
email:
type: string
description: The email address to validate.
@ -85,20 +86,28 @@ paths:
Session created.
examples:
application/json: {
"sid": "1234"
}
"sid": "1234"
}
schema:
type: object
properties:
sid:
type: string
description: The session ID.
required: ['sid']
400:
description: |
An error ocurred. Some possible errors are:
- ``M_INVALID_EMAIL``: The email address provided was invalid.
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
examples:
application/json: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken":
post:
summary: Validate ownership of an email address.
@ -111,7 +120,7 @@ paths:
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -122,10 +131,10 @@ paths:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
@ -143,14 +152,15 @@ paths:
The success of the validation.
examples:
application/json: {
"success": true
}
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of an email address.
description: |-

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -29,7 +30,7 @@ paths:
description: |-
Sign invitation details.
The identity server will look up ``token`` which was stored in a call
The identity service will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
operationId: blindlySignStuff
parameters:
@ -38,24 +39,24 @@ paths:
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: Token from the call to ``store-invite``
description: The token from the call to ``store-invite``.
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.
required: ["mxid", "token", "private_key"]
responses:
200:
description: The signedjson of the mxid, sender, and token.
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
@ -68,9 +69,11 @@ paths:
signatures:
type: object
description: The signature of the mxid, sender, and token.
$ref: "../../schemas/server-signatures.yaml"
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
examples:
application/json: {
"mxid": "@foo:bar.com",
@ -83,8 +86,11 @@ paths:
"token": "abc123"
}
404:
description: Token was not found.
example: {
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

@ -1,6 +1,7 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -20,8 +21,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -46,31 +48,30 @@ paths:
responses:
200:
description:
The association for that 3pid, or the empty object if no association is known.
The association for that 3pid, or an empty object if no association is known.
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"
}
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up.
description: The 3pid address of the user being looked up, matching the address requested.
medium:
type: string
description: The literal string "email".
description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
@ -86,6 +87,15 @@ paths:
signatures:
type: object
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
$ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
"/bulk_lookup":
post:
summary: Lookup Matrix user IDs for a list of 3pids.
@ -110,10 +120,17 @@ paths:
items:
type: array
title: 3PID mappings
minItems: 2
maxItems: 2
items:
type: string
title: 3PID medium or address
description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
# TODO: Give real names to these values. Adding a `title` does not work.
#- type: 3PID Medium
#- type: 3PID Address
- type: string
- type: string
description: |-
An array of arrays containing the `3PID Types`_ with the ``medium``
in first position and the ``address`` in second position.
required:
- "threepids"
responses:
@ -134,9 +151,19 @@ paths:
items:
type: array
title: 3PID mappings
minItems: 3
maxItems: 3
items:
type: string
title: 3PID medium or address or the Matrix ID
description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
# TODO: Give real names to these values. Adding a `title` does not work.
#- type: 3PID Medium
#- type: 3PID Address
#- type: Matrix User ID
- type: string
- type: string
- type: string
description: |-
An array of array containing the `3PID Types`_ with the ``medium``
in first position, the ``address`` in second position and Matrix user
ID in third position.
required:
- "threepids"

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -34,13 +35,13 @@ paths:
indicates that that user was able to read the SMS for that phone
number, and so we validate ownership of the phone number.
Note that Home Servers offer APIs that proxy this API, adding
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/msisdn/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the phone
number given is already registered on the server.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -51,11 +52,11 @@ paths:
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"country": "GB",
"phone_number": "07700900001",
"send_attempt": 1
}
"client_secret": "monkeys_are_GREAT",
"country": "GB",
"phone_number": "07700900001",
"send_attempt": 1
}
properties:
client_secret:
type: string
@ -91,20 +92,30 @@ paths:
Session created.
examples:
application/json: {
"sid": "1234"
}
"sid": "1234"
}
schema:
type: object
properties:
sid:
type: string
description: The session ID.
required: ['sid']
400:
description: |
An error ocurred. Some possible errors are:
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
- ``M_SEND_ERROR``: The validation SMS could not be sent.
- ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken":
post:
summary: Validate ownership of a phone number.
@ -117,7 +128,7 @@ paths:
associate the phone number address with any Matrix user
ID. Specifically, calls to ``/lookup`` will not show a binding.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -128,10 +139,10 @@ paths:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
@ -149,14 +160,15 @@ paths:
The success of the validation.
examples:
application/json: {
"success": true
}
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of a phone number.
description: |-

@ -1,4 +1,5 @@
# Copyright 2018 Kamax Sàrl
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -14,7 +15,7 @@
swagger: "2.0"
info:
title: "Matrix Client-Identity Versions API"
title: "Matrix Identity Service Ping API"
version: "1.0.0"
host: localhost:8090
schemes:
@ -25,19 +26,19 @@ produces:
paths:
"/api/v1":
get:
summary: Checks that an Identity server is available at this API endpopint.
summary: Checks that an Identity Service is available at this API endpoint.
description: |-
Checks that an Identity server is available at this API endpopint.
Checks that an Identity Service is available at this API endpoint.
To discover that an Identity server is available at a specific URL,
To discover that an Identity Service is available at a specific URL,
this endpoint can be queried and will return an empty object.
This is primarly used for auto-discovery and health check purposes
by entities acting as a client for the Identity server.
by entities acting as a client for the Identity Service.
operationId: ping
responses:
200:
description: An Identity server is ready to serve requests.
description: An Identity Service is ready to serve requests.
examples:
application/json: {}
schema:

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -45,13 +46,25 @@ paths:
The public key exists.
examples:
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
schema:
type: object
properties:
public_key:
type: string
description: Unpadded Base64 encoded public key.
required: ['public_key']
404:
description:
The public key was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid":
get:
summary: Check whether a long-term public key is valid.
@ -72,14 +85,15 @@ paths:
The validity of the public key.
examples:
application/json: {
"valid": true
}
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
get:
summary: Check whether a short-term public key is valid.
@ -100,11 +114,12 @@ paths:
The validity of the public key.
examples:
application/json: {
"valid": true
}
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']

@ -18,16 +18,17 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/store-invite":
post:
summary: Store pending invitations to a user\'s 3pid.
summary: Store pending invitations to a user's 3pid.
description: |-
Store pending invitations to a user\'s 3pid.
Store pending invitations to a user's 3pid.
In addition to the request parameters specified below, an arbitrary
number of other parameters may also be specified. These may be used in
@ -47,6 +48,8 @@ paths:
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
Currently, invites may only be issued for 3pids of the ``email`` medium.
operationId: storeInvite
parameters:
- in: body
@ -54,11 +57,11 @@ paths:
schema:
type: object
example: {
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
properties:
medium:
type: string
@ -84,21 +87,22 @@ paths:
description: The generated token.
public_keys:
type: array
description: A list of [server\'s long-term public key, generated ephemeral public key].
description: A list of [server's long-term public key, generated ephemeral public key].
items:
type: string
display_name:
type: string
description: The generated (redacted) display_name.
required: ['token', 'public_keys', 'display_name']
example:
application/json: {
"token": "sometoken",
"public_keys": [
"serverpublickey",
"ephemeralpublickey"
],
"display_name": "f...@b..."
}
"token": "sometoken",
"public_keys": [
"serverpublickey",
"ephemeralpublickey"
],
"display_name": "f...@b..."
}
400:
description: |
An error has occured.
@ -108,7 +112,9 @@ paths:
error code will be ``M_UNRECOGNIZED``.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": mxid
}
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

@ -31,7 +31,7 @@ properties:
example: 1532991320875
pdus:
type: array
description: List of persistent updates to rooms.
description: List of persistent updates to rooms. Must not include more than 50 PDUs.
items:
$ref: "pdu.yaml"
required: ['origin', 'origin_server_ts', 'pdus']

@ -49,7 +49,8 @@ paths:
responses:
200:
description: |-
The fully resolved state for the room, including the authorization
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object
@ -96,7 +97,8 @@ paths:
responses:
200:
description: |-
The fully resolved state for the room, including the authorization
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object

@ -49,6 +49,20 @@ paths:
A pagination token from a previous call to this endpoint to fetch more
rooms.
x-example: "GetMoreRoomsTokenHere"
- in: query
name: include_all_networks
type: boolean
description: |-
Whether or not to include all networks/protocols defined by application
services on the homeserver. Defaults to false.
x-example: false
- in: query
name: third_party_instance_id
type: string
description: |-
The specific third party network/protocol to request from the homeserver.
Can only be used if ``include_all_networks`` is false.
x-example: "irc"
responses:
200:
description: The public room list for the homeserver.

@ -60,8 +60,8 @@ paths:
edus:
type: array
description: |-
List of ephemeral messages. May be omitted if there are no ephemeral
messages to be sent.
List of ephemeral messages. May be omitted if there are no ephemeral
messages to be sent. Must not include more than 100 EDUs.
items:
$ref: "definitions/edu.yaml"
example: {

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../application_service.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

@ -0,0 +1 @@
Specify how to control the power level required for ``@room``

@ -0,0 +1 @@
Add ``.well-known`` server discovery method

@ -0,0 +1 @@
Share room decryption keys between devices

@ -0,0 +1 @@
Add a common standard for user, room, and group mentions in messages.

@ -0,0 +1 @@
Add server ACLs as an option for controlling federation in a room.

@ -0,0 +1 @@
Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.

@ -0,0 +1 @@
Add new push rules for encrypted events and ``@room`` notifications.

@ -0,0 +1 @@
Add third party network room directories, as provided by application services.

@ -0,0 +1 @@
Update all event examples to be accurate representations of their associated events.

@ -0,0 +1 @@
Clarify the supported HTML features for room messages.

@ -0,0 +1 @@
Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.

@ -0,0 +1 @@
Clarify the object structures and defaults for Filters.

@ -0,0 +1 @@
Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions.

@ -0,0 +1 @@
Clarify that left rooms also have account data in ``/sync``.

@ -0,0 +1 @@
Fix naming of the body field in ``PUT /directory/room``.

@ -0,0 +1 @@
Clarify the filter object schema used in room searching.

@ -0,0 +1 @@
Document the 403 error for sending state events.

@ -0,0 +1 @@
specify how to handle multiple olm sessions with the same device

@ -0,0 +1 @@
Add more presence options to the ``set_presence`` parameter of ``/sync``. (Thanks @mujx!)

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../identity_service.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

@ -0,0 +1,6 @@
r0.1.0
======
The first release of the Push Gateway specification. This release contains
a single endpoint, ``/notify``, that pushers may use to send push notifications
to clients.

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../push_gateway.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../server_server.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

@ -44,16 +44,51 @@ except ImportError as e:
raise
def load_file(path):
print("Loading reference: %s" % path)
if not path.startswith("file://"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
if path.endswith(".json"):
return json.load(f)
else:
# We have to assume it's YAML because some of the YAML examples
# do not have file extensions.
return yaml.load(f)
def resolve_references(path, schema):
if isinstance(schema, dict):
# do $ref first
if '$ref' in schema:
value = schema['$ref']
path = os.path.abspath(os.path.join(os.path.dirname(path), value))
ref = load_file("file://" + path)
result = resolve_references(path, ref)
del schema['$ref']
else:
result = {}
for key, value in schema.items():
result[key] = resolve_references(path, value)
return result
elif isinstance(schema, list):
return [resolve_references(path, value) for value in schema]
else:
return schema
def check_example_file(examplepath, schemapath):
with open(examplepath) as f:
example = yaml.load(f)
example = resolve_references(examplepath, json.load(f))
with open(schemapath) as f:
schema = yaml.load(f)
fileurl = "file://" + os.path.abspath(schemapath)
schema["id"] = fileurl
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml})
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file})
print ("Checking schema for: %r %r" % (examplepath, schemapath))
try:
@ -71,6 +106,10 @@ def check_example_dir(exampledir, schemadir):
if filename.startswith("."):
# Skip over any vim .swp files.
continue
cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
if cwd == "core":
# Skip checking the underlying definitions
continue
examplepath = os.path.join(root, filename)
schemapath = examplepath.replace(exampledir, schemadir)
if schemapath.find("#") >= 0:
@ -85,14 +124,6 @@ def check_example_dir(exampledir, schemadir):
raise ValueError("Error validating examples")
def load_yaml(path):
if not path.startswith("file:///"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
return yaml.load(f)
if __name__ == '__main__':
try:
check_example_dir("examples", "schema")

@ -0,0 +1,6 @@
{
"content": {
"key": "value"
},
"type": "org.example.custom.event"
}

@ -0,0 +1,4 @@
{
"$ref": "event.json",
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com"
}

@ -0,0 +1,10 @@
{
"$ref": "event.json",
"event_id": "$143273582443PhrSn:domain.com",
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
"sender": "@example:domain.com",
"origin_server_ts": 1432735824653,
"unsigned": {
"age": 1234
}
}

@ -0,0 +1,4 @@
{
"$ref": "room_event.json",
"state_key": "ArbitraryString"
}

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.answer",
"content": {
"version" : 0,
"call_id": "12345",
@ -8,10 +9,5 @@
"type" : "answer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.answer",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.candidates",
"content": {
"version" : 0,
"call_id": "12345",
@ -10,10 +11,5 @@
"candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
}
]
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.candidates",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.hangup",
"content": {
"version" : 0,
"call_id": "12345"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.hangup",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.invite",
"content": {
"version" : 0,
"call_id": "12345",
@ -8,10 +9,5 @@
"type" : "offer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.invite",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,9 +1,10 @@
{
"$ref": "core/event.json",
"type": "m.direct",
"content": {
"@bob:example.com": [
"!abcdefgh:example.com",
"!hgfedcba:example.com"
]
"!abcdefgh:example.com",
"!hgfedcba:example.com"
]
}
}

@ -0,0 +1,14 @@
{
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
"sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
"forwarding_curve25519_key_chain": [
"hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
]
},
"type": "m.forwarded_room_key"
}

@ -1,4 +1,5 @@
{
"$ref": "core/event.json",
"type": "m.ignored_user_list",
"content": {
"ignored_users": {

@ -1,10 +1,11 @@
{
"$ref": "core/event.json",
"sender": "@example:localhost",
"type": "m.presence",
"content": {
"avatar_url": "mxc://localhost:wefuiwegh8742w",
"last_active_ago": 2478593,
"presence": "online",
"currently_active": false
},
"sender": "@example:localhost",
"type": "m.presence"
}
}

@ -1,13 +1,13 @@
{
"type": "m.receipt",
"room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"m.read": {
"@rikj:jki.re": {
"ts": 1436451550453
}
}
"$ref": "core/room_edu.json",
"type": "m.receipt",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"m.read": {
"@rikj:jki.re": {
"ts": 1436451550453
}
}
}
}
}

@ -1,12 +1,8 @@
{
"age": 242352,
"content": {
"aliases": ["#somewhere:localhost", "#another:localhost"]
},
"state_key": "localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"$ref": "core/state_event.json",
"state_key": "domain.com",
"type": "m.room.aliases",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"content": {
"aliases": ["#somewhere:domain.com", "#another:domain.com"]
}
}

@ -1,5 +1,7 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.avatar",
"state_key": "",
"content": {
"info": {
"h": 398,
@ -7,12 +9,6 @@
"mimetype": "image/jpeg",
"size": 31037
},
"url": "mxc://localhost/JWEIFJgwEIhweiWJE"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.avatar",
"state_key": "",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"url": "mxc://domain.com/JWEIFJgwEIhweiWJE"
}
}

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.canonical_alias",
"state_key": "",
"content": {
"alias": "#somewhere:localhost"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.canonical_alias",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,12 +1,10 @@
{
"age": 242352,
"content": {
"creator": "@example:localhost"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"$ref": "core/state_event.json",
"type": "m.room.create",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"state_key": "",
"content": {
"creator": "@example:domain.com",
"room_version": "1",
"m.federate": true
}
}

@ -1,14 +1,11 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...",
"device_id": "RJYKSTBOIE",
"sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
},
"event_id": "$WLGTSEFSEF:localhost",
"room_id": "!Cuyf34gef24t:localhost",
"origin_server_ts": 1476648761524,
"sender": "@example:localhost",
"type": "m.room.encrypted"
}
}

@ -1,6 +1,6 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"sender": "@example:localhost",
"content": {
"algorithm": "m.olm.v1.curve25519-aes-sha2",
"sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU",

@ -1,13 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.room.encryption",
"state_key": "",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"rotation_period_ms": 604800000,
"rotation_period_msgs": 100
},
"event_id": "$WLGTSEFJJKJ:localhost",
"origin_server_ts": 1476648761524,
"sender": "@example:localhost",
"room_id": "!Cuyf34gef24t:localhost",
"state_key": "",
"type": "m.room.encryption"
}
}

@ -1,12 +1,8 @@
{
"age": 242353,
"$ref": "core/state_event.json",
"type": "m.room.guest_access",
"state_key": "",
"content": {
"guest_access": "can_join"
},
"state_key": "",
"origin_server_ts": 1431961217938,
"event_id": "$WLGTSEFSEG:localhost",
"type": "m.room.guest_access",
"room_id": "!Cuyf34gef24u:localhost",
"sender": "@example:localhost"
}
}

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.history_visibility",
"state_key": "",
"content": {
"history_visibility": "shared"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.history_visibility",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "public"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.join_rules",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,14 +1,10 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"state_key": "@alice:domain.com",
"type": "m.room.member",
"content": {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
},
"state_key": "@alice:localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

@ -1,30 +1,27 @@
{
"age": 242352,
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
},
"invite_room_state": [
{
"type": "m.room.name",
"state_key": "",
"content": {
"name": "Forest of Magic"
"unsigned": {
"age": 1234,
"invite_room_state": [
{
"type": "m.room.name",
"state_key": "",
"content": {
"name": "Forest of Magic"
}
},
{
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
},
{
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
],
"state_key": "@alice:localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
]
}
}

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

Loading…
Cancel
Save