archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Change RST code formatting markup to Markdown

Browse Source
pull/977/head
Will 4 years ago committed by Richard van der Hoff
parent c7cf90abfa
commit 27f8867aa0
158 changed files with 931 additions and 931 deletions
Show Stats Download Patch File Download Diff File

8
data/api/application-service/definitions/protocol.yaml
Unescape Escape View File

@ -43,9 +43,9 @@ properties:
field_types:
title: Field Types
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.
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
@ -101,7 +101,7 @@ properties:
example: "mxc://example.org/JkLmNoPq"
fields:
type: object
description: Preset values for ``fields`` the client may use to search by.
description: Preset values for `fields` the client may use to search by.
example: {
"network": "freenode"
}

2
data/api/application-service/definitions/security.yaml
Unescape Escape View File

@ -13,6 +13,6 @@
# limitations under the License.
homeserverAccessToken:
type: apiKey
description: The ``hs_token`` provided by the application service's registration.
description: The `hs_token` provided by the application service's registration.
name: access_token
in: query

2
data/api/application-service/query_room.yaml
Unescape Escape View File

@ -34,7 +34,7 @@ paths:
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given room alias. The homeserver will only query room
aliases inside the application service's ``aliases`` namespace. The
aliases inside the application service's `aliases` namespace. The
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
operationId: queryRoomByAlias

2
data/api/application-service/query_user.yaml
Unescape Escape View File

@ -34,7 +34,7 @@ paths:
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given user ID. The homeserver will only query user IDs
inside the application service's ``users`` namespace. The homeserver will
inside the application service's `users` namespace. The homeserver will
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

2
data/api/application-service/transactions.yaml
Unescape Escape View File

@ -34,7 +34,7 @@ paths:
(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
from message events via the presence of a `state_key`, rather than
via the event type.
operationId: sendTransaction
security:

4
data/api/client-server/account-data.yaml
Unescape Escape View File

@ -33,7 +33,7 @@ paths:
description: |-
Set some account_data for the client. This config is only visible to the user
that set the account_data. The config will be synced to clients in the
top-level ``account_data``.
top-level `account_data`.
operationId: setAccountData
security:
- accessToken: []
@ -110,7 +110,7 @@ paths:
description: |-
Set some account_data for the client on a given room. This config is only
visible to the user that set the account_data. The config will be synced to
clients in the per-room ``account_data``.
clients in the per-room `account_data`.
operationId: setAccountDataPerRoom
security:
- accessToken: []

44
data/api/client-server/administrative_contact.yaml
Unescape Escape View File

@ -93,13 +93,13 @@ paths:
description: |-
Adds contact information to the user's account.
This endpoint is deprecated in favour of the more specific ``/3pid/add``
and ``/3pid/bind`` endpoints.
This endpoint is deprecated in favour of the more specific `/3pid/add`
and `/3pid/bind` endpoints.
**Note:**
Previously this endpoint supported a ``bind`` parameter. This parameter
has been removed, making this endpoint behave as though it was ``false``.
This results in this endpoint being an equivalent to ``/3pid/bind`` rather
Previously this endpoint supported a `bind` parameter. This parameter
has been removed, making this endpoint behave as though it was `false`.
This results in this endpoint being an equivalent to `/3pid/bind` rather
than dual-purpose.
operationId: post3PIDs
deprecated: true
@ -157,8 +157,8 @@ paths:
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's ``POST
/validate/email/submitToken`` endpoint (without the requirement
to the Identity Service API's `POST
/validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
@ -166,7 +166,7 @@ paths:
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the ``/versions`` response (ie: r0.5.0).
in the `/versions` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
403:
description: The credentials could not be verified with the identity server.
@ -294,7 +294,7 @@ paths:
Removes a third party identifier from the user's account. This might not
cause an unbind of the identifier from the identity server.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
Unlike other endpoints, this endpoint does not take an `id_access_token`
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: delete3pidFromAccount
@ -311,9 +311,9 @@ paths:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
@ -342,8 +342,8 @@ paths:
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. ``success`` indicates that the
indentity server has unbound the identifier whereas ``no-support``
the 3PID from the identity server. `success` indicates that the
indentity server has unbound the identifier whereas `no-support`
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
@ -359,7 +359,7 @@ paths:
Removes a user's third party identifier from the provided identity server
without removing it from the homeserver.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
Unlike other endpoints, this endpoint does not take an `id_access_token`
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: unbind3pidFromAccount
@ -376,9 +376,9 @@ paths:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
@ -407,8 +407,8 @@ paths:
- "success"
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. ``success`` indicates that the identity server has unbound the
identifier whereas ``no-support`` indicates that the identity server
the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: "success"
@ -456,7 +456,7 @@ paths:
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
@ -503,7 +503,7 @@ paths:
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:

2
data/api/client-server/appservice_room_directory.yaml
Unescape Escape View File

@ -40,7 +40,7 @@ paths:
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``)
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

8
data/api/client-server/banning.yaml
Unescape Escape View File

@ -62,7 +62,7 @@ paths:
reason:
type: string
description: The reason the user has been banned. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
`reason` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
@ -74,7 +74,7 @@ paths:
type: object
403:
description: |-
You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room.
@ -121,7 +121,7 @@ paths:
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
@ -134,7 +134,7 @@ paths:
type: object
403:
description: |-
You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room.
examples:

16
data/api/client-server/content-repo.yaml
Unescape Escape View File

@ -112,14 +112,14 @@ paths:
x-example: matrix.org
required: true
description: |
The server name from the ``mxc://`` URI (the authoritory component)
The server name from the `mxc://` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
The media ID from the `mxc://` URI (the path component)
- in: query
type: boolean
name: allow_remote
@ -177,20 +177,20 @@ paths:
x-example: matrix.org
required: true
description: |
The server name from the ``mxc://`` URI (the authoritory component)
The server name from the `mxc://` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
The media ID from the `mxc://` URI (the path component)
- in: path
type: string
name: fileName
x-example: filename.jpg
required: true
description: A filename to give in the ``Content-Disposition`` header.
description: A filename to give in the `Content-Disposition` header.
- in: query
type: boolean
name: allow_remote
@ -210,7 +210,7 @@ paths:
type: "string"
Content-Disposition:
description: |-
The ``fileName`` requested or the name of the file that was previously
The `fileName` requested or the name of the file that was previously
uploaded, if set.
type: "string"
schema:
@ -248,14 +248,14 @@ paths:
required: true
x-example: example.org
description: |
The server name from the ``mxc://`` URI (the authoritory component)
The server name from the `mxc://` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
The media ID from the `mxc://` URI (the path component)
- in: query
type: integer
x-example: 64

96
data/api/client-server/create_room.yaml
Unescape Escape View File

@ -38,41 +38,41 @@ paths:
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
1. The ``m.room.create`` event itself. Must be the first event in the
1. The `m.room.create` event itself. Must be the first event in the
room.
2. An ``m.room.member`` event for the creator to join the room. This is
2. An `m.room.member` event for the creator to join the room. This is
needed so the remaining events can be sent.
3. A default ``m.room.power_levels`` event, giving the room creator
3. A default `m.room.power_levels` event, giving the room creator
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
by the `power_level_content_override` parameter.
4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
4. Events set by the `preset`. Currently these are the `m.room.join_rules`,
`m.room.history_visibility`, and `m.room.guest_access` state events.
5. Events listed in ``initial_state``, in the order that they are
5. Events listed in `initial_state`, in the order that they are
listed.
6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic`
state events).
7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with
`membership: invite` and `m.room.third_party_invite`).
The available presets do the following with respect to room state:
======================== ============== ====================== ================ =========
Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other
Preset `join_rules` `history_visibility` `guest_access` Other
======================== ============== ====================== ================ =========
``private_chat`` ``invite`` ``shared`` ``can_join``
``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.
``public_chat`` ``public`` ``shared`` ``forbidden``
`private_chat` `invite` `shared` `can_join`
`trusted_private_chat` `invite` `shared` `can_join` All invitees are given the same power level as the room creator.
`public_chat` `public` `shared` `forbidden`
======================== ============== ====================== ================ =========
The server will create a ``m.room.create`` event in the room with the
The server will create a `m.room.create` event in the room with the
requesting user as the creator, alongside other keys provided in the
``creation_content``.
`creation_content`.
operationId: createRoom
security:
- accessToken: []
@ -97,12 +97,12 @@ paths:
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
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``.
`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: |-
@ -111,22 +111,22 @@ paths:
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``.
would be `#foo:example.com`.
The complete room alias will become the canonical alias for
the room.
name:
type: string
description: |-
If this is included, an ``m.room.name`` event will be sent
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``.
Events for more information on `m.room.name`.
topic:
type: string
description: |-
If this is included, an ``m.room.topic`` event will be sent
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``.
Events for more information on `m.room.topic`.
invite:
type: array
description: |-
@ -155,7 +155,7 @@ paths:
medium:
type: string
# TODO: Link to Identity Service spec when it eixsts
description: The kind of address being passed in the address field, for example ``email``.
description: The kind of address being passed in the address field, for example `email`.
address:
type: string
description: The invitee's third party identifier.
@ -165,16 +165,16 @@ paths:
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
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
Extra keys, such as `m.federate`, to be added to the content
of the `m.room.create`_ event. The server will clobber the following
keys: ``creator``, ``room_version``. Future versions of the specification
keys: `creator`, `room_version`. Future versions of the specification
may allow the server to clobber other keys.
initial_state:
type: array
@ -184,8 +184,8 @@ paths:
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
overriden by ``name`` and ``topic`` keys.
Takes precedence over events set by `preset`, but gets
overriden by `name` and `topic` keys.
items:
type: object
title: StateEvent
@ -207,16 +207,16 @@ paths:
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``.
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`_ for more information.
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`_ for more information.
power_level_content_override:
title: Power Level Event Content
type: object
@ -244,24 +244,24 @@ paths:
400:
description: |-
The request is invalid. A meaningful ``errcode`` and description
The request is invalid. A meaningful `errcode` and description
error text will be returned. Example reasons for rejection include:
- The request body is malformed (``errcode`` set to ``M_BAD_JSON``
or ``M_NOT_JSON``).
- The request body is malformed (`errcode` set to `M_BAD_JSON`
or `M_NOT_JSON`).
- The room alias specified is already taken (``errcode`` set to
``M_ROOM_IN_USE``).
- The room alias specified is already taken (`errcode` set to
`M_ROOM_IN_USE`).
- The initial state implied by the parameters to the request is
invalid: for example, the user's ``power_level`` is set below
that necessary to set the room name (``errcode`` set to
``M_INVALID_ROOM_STATE``).
invalid: for example, the user's `power_level` is set below
that necessary to set the room name (`errcode` set to
`M_INVALID_ROOM_STATE`).
- The homeserver doesn't support the requested room version, or
one or more users being invited to the new room are residents
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.
schema:
"$ref": "definitions/errors/error.yaml"

8
data/api/client-server/cross_signing.yaml
Unescape Escape View File

@ -110,9 +110,9 @@ paths:
The input was invalid in some way. This can include one of the
following error codes:
* ``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.
* ``M_MISSING_PARAM``: No master key is available.
* `M_MISSING_PARAM`: No master key is available.
schema:
type: object
example: {
@ -207,8 +207,8 @@ paths:
type: object
description: |-
A map from user ID to key ID to an error for any signatures
that failed. If a signature was invalid, the ``errcode`` will
be set to ``M_INVALID_SIGNATURE``.
that failed. If a signature was invalid, the `errcode` will
be set to `M_INVALID_SIGNATURE`.
additionalProperties:
type: object
additionalProperties:

2
data/api/client-server/definitions/cross_signing_key.yaml
Unescape Escape View File

@ -33,7 +33,7 @@ properties:
type: string
description: |-
The public key. The object must have exactly one property, whose name is
in the form ``<algorithm>:<unpadded_base64_public_key>``, and whose value
in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value
is the unpadded base64 public key.
example:
"ed25519:alice+base64+public+key": "alice+base64+public+key"

4
data/api/client-server/definitions/device_keys.yaml
Unescape Escape View File

@ -38,7 +38,7 @@ properties:
type: object
description: |-
Public identity keys. The names of the properties should be in the
format ``<algorithm>:<device_id>``. The keys themselves should be
format `<algorithm>:<device_id>`. The keys themselves should be
encoded as specified by the key algorithm.
additionalProperties:
type: string
@ -50,7 +50,7 @@ properties:
title: Signatures
description: |-
Signatures for the device key object. A map from user ID, to a map from
``<algorithm>:<device_id>`` to the signature.
`<algorithm>:<device_id>` to the signature.
The signature is calculated using the process described at `Signing
JSON`_.

4
data/api/client-server/definitions/event.yaml
Unescape Escape View File

@ -44,8 +44,8 @@ properties:
format: int64
type: integer
prev_content:
description: Optional. The previous ``content`` for this state. This will
be present only for state events appearing in the ``timeline``. If this
description: Optional. The previous `content` for this state. This will
be present only for state events appearing in the `timeline`. If this
is not a state event, or there is no previous content, this key will be
missing.
title: EventContent

6
data/api/client-server/definitions/event_filter.yaml
Unescape Escape View File

@ -19,14 +19,14 @@ properties:
not_senders:
description: A list of sender IDs to exclude. If this list is absent then no senders
are excluded. A matching sender will be excluded even if it is listed in the
``'senders'`` filter.
`'senders'` filter.
items:
type: string
type: array
not_types:
description: A list of event types to exclude. If this list is absent then no
event types are excluded. A matching type will be excluded even if it is listed
in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence
in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
of characters.
items:
type: string
@ -39,7 +39,7 @@ properties:
type: array
types:
description: A list of event types to include. If this list is absent then all
event types are included. A ``'*'`` can be used as a wildcard to match any sequence
event types are included. A `'*'` can be used as a wildcard to match any sequence
of characters.
items:
type: string

4
data/api/client-server/definitions/openid_token.yaml
Unescape Escape View File

@ -19,10 +19,10 @@ properties:
description: |-
An access token the consumer may use to verify the identity of
the person who generated the token. This is given to the federation
API ``GET /openid/userinfo`` to verify the user's identity.
API `GET /openid/userinfo` to verify the user's identity.
token_type:
type: string
description: The string ``Bearer``.
description: The string `Bearer`.
matrix_server_name:
type: string
description: |-

12
data/api/client-server/definitions/push_condition.yaml
Unescape Escape View File

@ -23,25 +23,25 @@ properties:
key:
type: string
description: |-
Required for ``event_match`` conditions. The dot-separated field of the
Required for `event_match` conditions. The dot-separated field of the
event to match.
Required for ``sender_notification_permission`` conditions. The field in
Required for `sender_notification_permission` conditions. The field in
the power level event the user needs a minimum power level for. Fields
must be specified under the ``notifications`` property in the power level
event's ``content``.
must be specified under the `notifications` property in the power level
event's `content`.
x-example: content.body
pattern:
type: string
description: |-
Required for ``event_match`` conditions. The glob-style pattern to
Required for `event_match` conditions. The glob-style pattern to
match against. Patterns with no special glob characters should be
treated as having asterisks prepended and appended when testing the
condition.
is:
type: string
description: |-
Required for ``room_member_count`` conditions. A decimal integer
Required for `room_member_count` conditions. A decimal integer
optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches
rooms where the member count is strictly less than the given number and
so forth. If no prefix is present, this parameter defaults to ==.

4
data/api/client-server/definitions/push_rule.yaml
Unescape Escape View File

@ -43,11 +43,11 @@ properties:
description: |-
The conditions that must hold true for an event in order for a rule to be
applied to an event. A rule with no conditions always matches. Only
applicable to ``underride`` and ``override`` rules.
applicable to `underride` and `override` rules.
pattern:
type: string
description: |-
The glob-style pattern to match against. Only applicable to ``content``
The glob-style pattern to match against. Only applicable to `content`
rules.
required:
- actions

4
data/api/client-server/definitions/request_email_validation.yaml
Unescape Escape View File

@ -24,7 +24,7 @@ allOf:
3PID verification.
This parameter is deprecated with a plan to be removed in a future specification
version for ``/account/password`` and ``/register`` requests.
version for `/account/password` and `/register` requests.
example: "id.example.com"
id_access_token:
type: string
@ -33,4 +33,4 @@ allOf:
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
Required if an ``id_server`` is supplied.
Required if an `id_server` is supplied.

4
data/api/client-server/definitions/request_msisdn_validation.yaml
Unescape Escape View File

@ -24,7 +24,7 @@ allOf:
3PID verification.
This parameter is deprecated with a plan to be removed in a future specification
version for ``/account/password`` and ``/register`` requests.
version for `/account/password` and `/register` requests.
example: "id.example.com"
id_access_token:
type: string
@ -33,4 +33,4 @@ allOf:
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
Required if an ``id_server`` is supplied.
Required if an `id_server` is supplied.

6
data/api/client-server/definitions/request_token_response.yaml
Unescape Escape View File

@ -17,7 +17,7 @@ properties:
type: string
description: |-
The session ID. Session IDs are opaque strings that must consist entirely
of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255
of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255
characters and they must not be empty.
example: "123abc"
submit_url:
@ -25,13 +25,13 @@ properties:
description: |-
An optional field containing a URL where the client must submit the
validation token to, with identical parameters to the Identity Service
API's ``POST /validate/email/submitToken`` endpoint (without the requirement
API's `POST /validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the user (if
applicable), who should then be prompted to provide it to the client.
If this field is not present, the client can assume that verification
will happen without the client's involvement provided the homeserver
advertises this specification version in the ``/versions`` response
advertises this specification version in the `/versions` response
(ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
required: ['sid']

16
data/api/client-server/definitions/room_event_filter.yaml
Unescape Escape View File

@ -19,20 +19,20 @@ allOf:
lazy_load_members:
type: boolean
description: |-
If ``true``, enables lazy-loading of membership events. See
If `true`, enables lazy-loading of membership events. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
for more information. Defaults to `false`.
include_redundant_members:
type: boolean
description: |-
If ``true``, sends all membership events for all events, even if they have already
If `true`, sends all membership events for all events, even if they have already
been sent to the client. Does not
apply unless ``lazy_load_members`` is ``true``. See
apply unless `lazy_load_members` is `true`. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
for more information. Defaults to `false`.
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'``
are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
filter.
items:
type: string
@ -45,5 +45,5 @@ allOf:
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a ``url`` key in their content. If
``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.
description: If `true`, includes only events with a `url` key in their content. If
`false`, excludes those events. If omitted, `url` key is not considered for filtering.

2
data/api/client-server/definitions/security.yaml
Unescape Escape View File

@ -13,6 +13,6 @@
# limitations under the License.
accessToken:
type: apiKey
description: The access_token returned by a call to ``/login`` or ``/register``
description: The access_token returned by a call to `/login` or `/register`
name: access_token
in: query

10
data/api/client-server/definitions/sync_filter.yaml
Unescape Escape View File

@ -46,16 +46,16 @@ properties:
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. This filter is applied before the filters in ``ephemeral``,
``state``, ``timeline`` or ``account_data``
are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
filter. This filter is applied before the filters in `ephemeral`,
`state`, `timeline` or `account_data`
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included. This filter is applied before the filters in ``ephemeral``,
``state``, ``timeline`` or ``account_data``
are included. This filter is applied before the filters in `ephemeral`,
`state`, `timeline` or `account_data`
items:
type: string
type: array

2
data/api/client-server/definitions/third_party_signed.yaml
Unescape Escape View File

@ -14,7 +14,7 @@
type: object
title: Third Party Signed
description: |-
A signature of an ``m.third_party_invite`` token to prove that this user
A signature of an `m.third_party_invite` token to prove that this user
owns a third party identity which has been invited to the room.
properties:
sender:

4
data/api/client-server/definitions/timeline_batch.yaml
Unescape Escape View File

@ -16,11 +16,11 @@ allOf:
- $ref: room_event_batch.yaml
properties:
limited:
description: True if the number of events returned was limited by the ``limit``
description: True if the number of events returned was limited by the `limit`
on the filter.
type: boolean
prev_batch:
description: A token that can be supplied to the ``from`` parameter of the
description: A token that can be supplied to the `from` parameter of the
rooms/{roomId}/messages endpoint.
type: string
type: object

10
data/api/client-server/directory.yaml
Unescape Escape View File

@ -133,11 +133,11 @@ paths:
room aliases can only be deleted by their creator or a server administrator.
**Note:**
Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias``
Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias`
state event in the room when an alias is removed. Servers which choose to update the
canonical alias event are recommended to, in addition to their other relevant permission
checks, delete the alias and return a successful response even if the user does not
have permission to update the ``m.room.canonical_alias`` event.
have permission to update the `m.room.canonical_alias` event.
operationId: deleteRoomAlias
security:
@ -176,8 +176,8 @@ paths:
given room.
This endpoint can be called by users who are in the room (external
users receive an ``M_FORBIDDEN`` error response). If the room's
``m.room.history_visibility`` maps to ``world_readable``, any
users receive an `M_FORBIDDEN` error response). If the room's
`m.room.history_visibility` maps to `world_readable`, any
user can call this endpoint.
Servers may choose to implement additional access control checks here,
@ -186,7 +186,7 @@ paths:
**Note:**
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.
operationId: getLocalAliases

8
data/api/client-server/event_context.yaml
Unescape Escape View File

@ -63,10 +63,10 @@ paths:
name: filter
type: string
description: |-
A JSON ``RoomEventFilter`` to filter the returned events with. The
filter is only applied to ``events_before``, ``events_after``, and
``state``. It is not applied to the ``event`` itself. The filter may
be applied before or/and after the ``limit`` parameter - whichever the
A JSON `RoomEventFilter` to filter the returned events with. The
filter is only applied to `events_before`, `events_after`, and
`state`. It is not applied to the `event` itself. The filter may
be applied before or/and after the `limit` parameter - whichever the
homeserver prefers.
See `Filtering <#filtering>`_ for more information.

2
data/api/client-server/filter.yaml
Unescape Escape View File

@ -88,7 +88,7 @@ paths:
type: string
description: |-
The ID of the filter that was created. Cannot start
with a ``{`` as this character is used to determine
with a `{` as this character is used to determine
if the filter provided is inline JSON or a previously
declared filter by homeservers on some APIs.
example: "66696p746572"

14
data/api/client-server/inviting.yaml
Unescape Escape View File

@ -48,7 +48,7 @@ paths:
join that room.
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.
.. _third party invites section: `invite-by-third-party-id-endpoint`_
operationId: inviteUser
@ -77,7 +77,7 @@ paths:
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
@ -91,20 +91,20 @@ paths:
400:
description: |-
The request is invalid. A meaningful ``errcode`` and description
The request is invalid. A meaningful `errcode` and description
error text will be returned. Example reasons for rejection include:
- The request body is malformed (``errcode`` set to ``M_BAD_JSON``
or ``M_NOT_JSON``).
- The request body is malformed (`errcode` set to `M_BAD_JSON`
or `M_NOT_JSON`).
- One or more users being invited to the room are residents of a
homeserver which does not support the requested room version. The
``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these cases.
`errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
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:
- The invitee has been banned from the room.
- The invitee is already a member of the room.

22
data/api/client-server/joining.yaml
Unescape Escape View File

@ -32,7 +32,7 @@ paths:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API requires a room ID, not alias.*
``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
`/join/{roomIdOrAlias}` *exists if you have a room alias.*
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
@ -62,12 +62,12 @@ paths:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If supplied, the homeserver must verify that it matches a pending
``m.room.third_party_invite`` event in the room, and perform
`m.room.third_party_invite` event in the room, and perform
key validity checking if required by the event.
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
responses:
@ -75,7 +75,7 @@ paths:
description: |-
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:
application/json: {
"room_id": "!d41d8cd:matrix.org"}
@ -88,7 +88,7 @@ paths:
required: ["room_id"]
403:
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:
- The room is invite-only and the user was not invited.
@ -108,7 +108,7 @@ paths:
post:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``.
*Note that this API takes either a room ID or alias, unlike* `/room/{roomId}/join`.
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
@ -146,13 +146,13 @@ paths:
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
If a `third_party_signed` was supplied, the homeserver must verify
that it matches a pending `m.room.third_party_invite` event in the
room, and perform key validity checking if required by the event.
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
Optional reason to be included as the `reason` on the subsequent
membership event.
example: "Looking for support"
responses:
@ -160,7 +160,7 @@ paths:
description: |-
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:
application/json: {
"room_id": "!d41d8cd:matrix.org"}
@ -173,7 +173,7 @@ paths:
required: ["room_id"]
403:
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:
- The room is invite-only and the user was not invited.

40
data/api/client-server/key_backup.yaml
Unescape Escape View File

@ -124,7 +124,7 @@ paths:
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the ``etag`` value they received
Clients can compare it with the `etag` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
@ -168,7 +168,7 @@ paths:
type: string
name: version
description: |-
The backup version to get, as returned in the ``version`` parameter
The backup version to get, as returned in the `version` parameter
of the response in `POST /_matrix/client/r0/room_keys/version`_ or
this endpoint.
required: true
@ -206,7 +206,7 @@ paths:
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the ``etag`` value they received
Clients can compare it with the `etag` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
@ -240,7 +240,7 @@ paths:
put:
summary: Update information about an existing backup.
description: |-
Update information about an existing backup. Only ``auth_data`` can be modified.
Update information about an existing backup. Only `auth_data` can be modified.
operationId: putRoomKeysVersion
security:
- accessToken: []
@ -249,7 +249,7 @@ paths:
type: string
name: version
description: |-
The backup version to update, as returned in the ``version``
The backup version to update, as returned in the `version`
parameter in the response of `POST
/_matrix/client/r0/room_keys/version`_ or `GET
/_matrix/client/r0/room_keys/version/{version}`_.
@ -300,9 +300,9 @@ paths:
properties: {}
400:
description: |-
A parameter was incorrect. For example, the ``algorithm`` does not
match the current backup algorithm, or the ``version`` in the body
does not match the ``version`` in the path.
A parameter was incorrect. For example, the `algorithm` does not
match the current backup algorithm, or the `version` in the body
does not match the `version` in the path.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
@ -338,7 +338,7 @@ paths:
type: string
name: version
description: |-
The backup version to delete, as returned in the ``version``
The backup version to delete, as returned in the `version`
parameter in the response of `POST
/_matrix/client/r0/room_keys/version`_ or `GET
/_matrix/client/r0/room_keys/version/{version}`_.
@ -412,7 +412,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:
@ -425,7 +425,7 @@ paths:
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
The current version will be included in the `current_version`
field.
examples:
application/json: {
@ -522,7 +522,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:
@ -583,7 +583,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:
@ -596,7 +596,7 @@ paths:
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
The current version will be included in the `current_version`
field.
examples:
application/json: {
@ -647,7 +647,7 @@ paths:
200:
description: |-
The key data. If no keys are found, then an object with an empty
``sessions`` property will be returned (``{"sessions": {}}``).
`sessions` property will be returned (`{"sessions": {}}`).
schema:
type: object
$ref: "definitions/room_key_backup.yaml"
@ -695,7 +695,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:
@ -776,7 +776,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:
@ -789,7 +789,7 @@ paths:
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
The current version will be included in the `current_version`
field.
examples:
application/json: {
@ -834,7 +834,7 @@ paths:
200:
description: |-
The key data. If no keys are found, then an object with an empty
``rooms`` property will be returned (``{"rooms": {}}``).
`rooms` property will be returned (`{"rooms": {}}`).
schema:
type: object
properties:
@ -898,7 +898,7 @@ paths:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
See `GET /room_keys/version/{version}` for more details.
type: string
example: "abcdefg"
count:

26
data/api/client-server/keys.yaml
Unescape Escape View File

@ -57,7 +57,7 @@ paths:
description: |-
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
``<algorithm>:<key_id>``. The format of the key is determined
`<algorithm>:<key_id>`. The format of the key is determined
by the `key algorithm <#key-algorithms>`_.
May be absent if no new one-time keys are required.
@ -184,7 +184,7 @@ paths:
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.
user or device is missing from the `device_keys` result.
additionalProperties:
type: object
example: {}
@ -194,7 +194,7 @@ paths:
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``
`/keys/upload`, with the addition of an `unsigned`
property.
additionalProperties:
type: object
@ -243,8 +243,8 @@ paths:
Information on the master cross-signing keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
``/keys/device_signing/upload``, along with the signatures
uploaded via ``/keys/signatures/upload`` that the requesting user
`/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the requesting user
is allowed to see.
additionalProperties:
allOf:
@ -264,7 +264,7 @@ paths:
Information on the self-signing keys of the queried users. A map
from user ID, to self-signing key information. For each key, the
information returned will be the same as uploaded via
``/keys/device_signing/upload``.
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
@ -289,7 +289,7 @@ paths:
request, if they queried their own device information. A map
from user ID, to user-signing key information. The
information returned will be the same as uploaded via
``/keys/device_signing/upload``.
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
@ -364,7 +364,7 @@ paths:
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.
user or device is missing from the `one_time_keys` result.
additionalProperties:
type: object
example: {}
@ -372,7 +372,7 @@ paths:
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.
map from devices to a map from `<algorithm>:<key_id>` to the key object.
See the `key algorithms <#key-algorithms>`_ section for information
on the Key Object format.
@ -425,9 +425,9 @@ paths:
The server should include in the results any users who:
* currently share a room with the calling user (ie, both users have
membership state ``join``); *and*
membership state `join`); *and*
* added new device identity keys or removed an existing device with
identity keys, between ``from`` and ``to``.
identity keys, between `from` and `to`.
operationId: getKeysChanges
security:
- accessToken: []
@ -436,7 +436,7 @@ paths:
name: from
type: string
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|. Users who have not
uploaded new device identity keys since this point, nor deleted
existing devices with identity keys since then, will be excluded
@ -447,7 +447,7 @@ paths:
name: to
type: string
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| - typically the most recent
such call. This may be used by the server as a hint to check its
caches are up to date.

14
data/api/client-server/kicking.yaml
Unescape Escape View File

@ -34,10 +34,10 @@ paths:
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
Kicking a user adjusts the target member's membership state to be ``leave`` with an
optional ``reason``. Like with other membership changes, a user can directly adjust
the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
Kicking a user adjusts the target member's membership state to be `leave` with an
optional `reason`. Like with other membership changes, a user can directly adjust
the target member's state by making a request to `/rooms/<room id>/state/m.room.member/<user id>`.
operationId: kick
security:
- accessToken: []
@ -64,8 +64,8 @@ paths:
reason:
type: string
description: |-
The reason the user has been kicked. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
The reason the user has been kicked. This will be supplied as the
`reason` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
@ -77,7 +77,7 @@ paths:
type: object
403:
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:
- The kicker is not currently in the room.

2
data/api/client-server/leaving.yaml
Unescape Escape View File

@ -64,7 +64,7 @@ paths:
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
Optional reason to be included as the `reason` on the subsequent
membership event.
responses:
200:

2
data/api/client-server/list_joined_rooms.yaml
Unescape Escape View File

@ -45,7 +45,7 @@ paths:
joined_rooms:
type: array
description: |-
The ID of each room in which the user has ``joined`` membership.
The ID of each room in which the user has `joined` membership.
items:
type: string
examples:

12
data/api/client-server/list_public_rooms.yaml
Unescape Escape View File

@ -48,7 +48,7 @@ paths:
type: string
enum: ['private', 'public']
description: The visibility of the room in the directory.
examples:
examples:
application/json: {
"visibility": "public"
}
@ -68,7 +68,7 @@ paths:
directory.
Servers may choose to implement additional access control checks
here, for instance that room visibility can only be changed by
here, for instance that room visibility can only be changed by
the room creator or a server administrator.
operationId: setRoomVisibilityOnDirectory
security:
@ -92,7 +92,7 @@ paths:
type: string
enum: ["private", "public"]
description: |-
The new visibility setting for the room.
The new visibility setting for the room.
Defaults to 'public'.
example: {
"visibility": "public"
@ -100,7 +100,7 @@ paths:
responses:
200:
description: The visibility was updated, or no change was needed.
examples:
examples:
application/json: {}
404:
description: The room is not known to the server
@ -204,10 +204,10 @@ paths:
type: string
description: |-
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: {
"limit": 10,
"limit": 10,
"filter": {
"generic_search_term": "foo"
},

28
data/api/client-server/login.yaml
Unescape Escape View File

@ -33,7 +33,7 @@ paths:
summary: Get the supported login types to authenticate users
description: |-
Gets the homeserver's supported login types to authenticate users. Clients
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
responses:
200:
@ -56,7 +56,7 @@ paths:
properties:
type:
description: |-
The login type. This is supplied as the ``type`` when
The login type. This is supplied as the `type` when
logging in.
type: string
429:
@ -71,10 +71,10 @@ paths:
Authenticates the user, and issues an access token they can
use to authorize themself in subsequent requests.
If the client does not supply a ``device_id``, the server must
If the client does not supply a `device_id`, the server must
auto-generate one.
The returned access token must be associated with the ``device_id``
The returned access token must be associated with the `device_id`
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
@ -103,22 +103,22 @@ paths:
"$ref": "definitions/user_identifier.yaml"
user:
type: string
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of ``identifier``.
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`.
medium:
type: string
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of ``identifier``.
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
address:
type: string
description: Third party identifier for the user. Deprecated in favour of ``identifier``.
description: Third party identifier for the user. Deprecated in favour of `identifier`.
password:
type: string
description: |-
Required when ``type`` is ``m.login.password``. The user's
Required when `type` is `m.login.password`. The user's
password.
token:
type: string
description: |-
Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login.
Required when `type` is `m.login.token`. Part of `Token-based`_ login.
device_id:
type: string
description: |-
@ -131,7 +131,7 @@ paths:
type: string
description: |-
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.
required: ["type"]
responses:
@ -169,8 +169,8 @@ paths:
been registered.
**Deprecated**. Clients should extract the server_name from
``user_id`` (by splitting at the first colon) if they require
it. Note also that ``homeserver`` is not spelt this way.
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
@ -197,10 +197,10 @@ paths:
403:
description: |-
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
ID.
* ``M_USER_DEACTIVATED``: The user has been deactivated.
* `M_USER_DEACTIVATED`: The user has been deactivated.
examples:
application/json: {
"errcode": "M_FORBIDDEN"

30
data/api/client-server/message_pagination.yaml
Unescape Escape View File

@ -51,8 +51,8 @@ paths:
name: from
description: |-
The token to start returning events from. This token can be obtained
from a ``prev_batch`` token returned for each room by the sync API,
or from a ``start`` or ``end`` token returned by a previous request
from a `prev_batch` token returned for each room by the sync API,
or from a `start` or `end` token returned by a previous request
to this endpoint.
required: true
x-example: "s345_678_333"
@ -61,8 +61,8 @@ paths:
name: to
description: |-
The token to stop returning events at. This token can be obtained from
a ``prev_batch`` token returned for each room by the sync endpoint,
or from a ``start`` or ``end`` token returned by a previous request to
a `prev_batch` token returned for each room by the sync endpoint,
or from a `start` or `end` token returned by a previous request to
this endpoint.
required: false
- in: query
@ -96,30 +96,30 @@ paths:
start:
type: string
description: |-
The token the pagination starts from. If ``dir=b`` this will be
the token supplied in ``from``.
The token the pagination starts from. If `dir=b` this will be
the token supplied in `from`.
end:
type: string
description: |-
The token the pagination ends at. If ``dir=b`` this token should
The token the pagination ends at. If `dir=b` this token should
be used again to request even earlier events.
chunk:
type: array
description: |-
A list of room events. The order depends on the ``dir`` parameter.
For ``dir=b`` events will be in reverse-chronological order,
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
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, so that events start
at the `from` point.
items:
"$ref": "../../event-schemas/schema/core-event-schema/room_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``.
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
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.

6
data/api/client-server/notifications.yaml
Unescape Escape View File

@ -54,7 +54,7 @@ paths:
name: only
type: string
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
tweak set.
required: false
@ -87,8 +87,8 @@ paths:
next_token:
type: string
description: |-
The token to supply in the ``from`` param of the next
``/notifications`` request in order to request more
The token to supply in the `from` param of the next
`/notifications` request in order to request more
events. If this is absent, there are no more results.
notifications:
type: array

38
data/api/client-server/old_sync.yaml
Unescape Escape View File

@ -32,10 +32,10 @@ paths:
summary: Listen on the event stream.
description: |-
This will listen for new events and return them to the caller. This will
block until an event is received, or until the ``timeout`` is reached.
block until an event is received, or until the `timeout` is reached.
This endpoint was deprecated in r0 of this specification. Clients
should instead call the |/sync|_ API with a ``since`` parameter. See
should instead call the |/sync|_ API with a `since` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: getEvents
@ -73,13 +73,13 @@ paths:
start:
type: string
description: |-
A token which correlates to the first value in ``chunk``. This
is usually the same token supplied to ``from=``.
A token which correlates to the first value in `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``. This
token should be used in the next request to ``/events``.
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."
@ -89,7 +89,7 @@ paths:
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
description: "Bad pagination `from` parameter."
tags:
- Room participation
deprecated: true
@ -101,7 +101,7 @@ paths:
number of messages per room to return.
This endpoint was deprecated in r0 of this specification. Clients
should instead call the |/sync|_ API with no ``since`` parameter. See
should instead call the |/sync|_ API with no `since` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: initialSync
@ -118,10 +118,10 @@ paths:
type: boolean
name: archived
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
only rooms that the user has been invited to or has joined are
included. If set to ``true`` then rooms that the user has left are
included as well. By default this is ``false``.
included. If set to `true` then rooms that the user has left are
included as well. By default this is `false`.
required: false
x-example: "true"
responses:
@ -199,8 +199,8 @@ paths:
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``. This
token should be used with the ``/events`` API to listen for new
A token which correlates to the last value in `chunk`. This
token should be used with the `/events` API to listen for new
events.
presence:
type: array
@ -226,7 +226,7 @@ paths:
invite:
type: object
title: "InviteEvent"
description: "The invite event if ``membership`` is ``invite``"
description: "The invite event if `membership` is `invite`"
allOf:
- "$ref": "../../event-schemas/schema/m.room.member.yaml"
messages:
@ -237,12 +237,12 @@ paths:
start:
type: string
description: |-
A token which correlates to the first value in ``chunk``.
A token which correlates to the first value in `chunk`.
Used for pagination.
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``.
A token which correlates to the last value in `chunk`.
Used for pagination.
chunk:
type: array
@ -251,7 +251,7 @@ paths:
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceeded them leaving. This array
will consist of at most ``limit`` elements.
will consist of at most `limit` elements.
items:
type: object
title: RoomEvent
@ -274,7 +274,7 @@ paths:
type: string
enum: ["private", "public"]
description: |-
Whether this room is visible to the ``/publicRooms`` API
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array
@ -306,7 +306,7 @@ paths:
get:
summary: Get a single event by event ID.
description: |-
Get a single event based on ``event_id``. You must have permission to
Get a single event based on `event_id`. You must have permission to
retrieve this event e.g. by being a member in the room for this event.
This endpoint was deprecated in r0 of this specification. Clients

4
data/api/client-server/openid.yaml
Unescape Escape View File

@ -37,7 +37,7 @@ paths:
OpenID.
The access token generated is only valid for the OpenID API. It cannot
be used to request another OpenID access token or call ``/sync``, for
be used to request another OpenID access token or call `/sync`, for
example.
operationId: requestOpenIdToken
security:
@ -63,7 +63,7 @@ paths:
description: |-
OpenID token information. This response is nearly compatible with the
response documented in the `OpenID Connect 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
with the only difference being the lack of an ``id_token``. Instead,
with the only difference being the lack of an `id_token`. Instead,
the Matrix homeserver's name is provided.
examples:
application/json: {

16
data/api/client-server/peeking_events.yaml
Unescape Escape View File

@ -33,12 +33,12 @@ paths:
description: |-
This will listen for new events related to a particular room and return
them to the caller. This will block until an event is received, or until
the ``timeout`` is reached.
the `timeout` is reached.
This API is the same as the normal ``/events`` endpoint, but can be
This API is the same as the normal `/events` endpoint, but can be
called by users who have not joined the room.
Note that the normal ``/events`` endpoint has been deprecated. This
Note that the normal `/events` endpoint has been deprecated. This
API will also be deprecated at some point, but its replacement is not
yet known.
operationId: peekEvents
@ -86,13 +86,13 @@ paths:
start:
type: string
description: |-
A token which correlates to the first value in ``chunk``. This
is usually the same token supplied to ``from=``.
A token which correlates to the first value in `chunk`. This
is usually the same token supplied to `from=`.
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``. This
token should be used in the next request to ``/events``.
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."
@ -102,5 +102,5 @@ paths:
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
description: "Bad pagination `from` parameter."
# No tags to exclude this from the swagger UI - use the normal version instead.

2
data/api/client-server/presence.yaml
Unescape Escape View File

@ -33,7 +33,7 @@ paths:
description: |-
This API sets the given user's presence state. When setting the status,
the activity time is updated to reflect that activity; the client does
not need to specify the ``last_active_ago`` field. You cannot set the
not need to specify the `last_active_ago` field. You cannot set the
presence state of another user.
operationId: setPresence
security:

6
data/api/client-server/profile.yaml
Unescape Escape View File

@ -32,7 +32,7 @@ paths:
summary: Set the user's display name.
description: |-
This API sets the given user's display name. You must have permission to
set this user's display name, e.g. you need to have their ``access_token``.
set this user's display name, e.g. you need to have their `access_token`.
operationId: setDisplayName
security:
- accessToken: []
@ -106,7 +106,7 @@ paths:
summary: Set the user's avatar URL.
description: |-
This API sets the given user's avatar URL. You must have permission to
set this user's avatar URL, e.g. you need to have their ``access_token``.
set this user's avatar URL, e.g. you need to have their `access_token`.
operationId: setAvatarUrl
security:
- accessToken: []
@ -182,7 +182,7 @@ paths:
Get the combined profile information for this user. This API may be used
to fetch the user's own profile information or other users; either
locally or on remote homeservers. This API may return keys which are not
limited to ``displayname`` or ``avatar_url``.
limited to `displayname` or `avatar_url`.
operationId: getUserProfile
parameters:
- in: path

28
data/api/client-server/pusher.yaml
Unescape Escape View File

@ -71,13 +71,13 @@ paths:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. See ``/set`` for
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
The kind of pusher. `"http"` is a pusher that
sends HTTP pokes.
app_id:
type: string
@ -114,7 +114,7 @@ paths:
url:
type: string
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.
format:
type: string
@ -173,14 +173,14 @@ paths:
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.
kind:
type: string
description: |-
The kind of pusher to configure. ``"http"`` makes a pusher that
sends HTTP pokes. ``"email"`` makes a pusher that emails the
user with unread notifications. ``null`` deletes the pusher.
The kind of pusher to configure. `"http"` makes a pusher that
sends HTTP pokes. `"email"` makes a pusher that emails the
user with unread notifications. `null` deletes the pusher.
app_id:
type: string
description: |-
@ -189,7 +189,7 @@ paths:
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:
type: string
description: |-
@ -214,22 +214,22 @@ paths:
type: object
description: |-
A dictionary of information for the pusher implementation
itself. If ``kind`` is ``http``, this should contain ``url``
itself. If `kind` is `http`, this should contain `url`
which is the URL to use to send notifications to.
title: PusherData
properties:
url:
type: string
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to. MUST be an HTTPS URL with a path of
``/_matrix/push/v1/notify``.
Required if `kind` is `http`. The URL to use to send
notifications to. MUST be an HTTPS URL with a path of
`/_matrix/push/v1/notify`.
example: "https://push-gateway.location.here/_matrix/push/v1/notify"
format:
type: string
description: |-
The format to send notifications in to Push Gateways if the
``kind`` is ``http``. The details about what fields the
`kind` is `http`. The details about what fields the
homeserver should send to the push gateway are defined in the
`Push Gateway Specification`_. Currently the only format
available is 'event_id_only'.
@ -240,7 +240,7 @@ paths:
given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different
users. The default is ``false``.
users. The default is `false`.
required: ['kind', 'app_id', 'app_display_name',
'device_display_name', 'pushkey', 'lang', 'data']
responses:

34
data/api/client-server/pushrules.yaml
Unescape Escape View File

@ -32,9 +32,9 @@ paths:
summary: Retrieve all push rulesets.
description: |-
Retrieve all push rulesets for this user. Clients can "drill-down" on
the rulesets by suffixing a ``scope`` to this path e.g.
``/pushrules/global/``. This will return a subset of this data under the
specified key e.g. the ``global`` key.
the rulesets by suffixing a `scope` to this path e.g.
`/pushrules/global/`. This will return a subset of this data under the
specified key e.g. the `global` key.
operationId: getPushRules
security:
- accessToken: []
@ -263,7 +263,7 @@ paths:
required: true
x-example: "global"
description: |-
``global`` to specify global rules.
`global` to specify global rules.
- in: path
type: string
name: kind
@ -283,7 +283,7 @@ paths:
200:
description: |-
The specific push rule. This will also include keys specific to the
rule itself such as the rule's ``actions`` and ``conditions`` if set.
rule itself such as the rule's `actions` and `conditions` if set.
examples:
application/json: {
"actions": [
@ -326,7 +326,7 @@ paths:
required: true
x-example: "global"
description: |-
``global`` to specify global rules.
`global` to specify global rules.
- in: path
type: string
name: kind
@ -380,7 +380,7 @@ paths:
required: true
x-example: "global"
description: |-
``global`` to specify global rules.
`global` to specify global rules.
- in: path
type: string
name: kind
@ -402,7 +402,7 @@ paths:
required: false
x-example: someRuleId
description: |-
Use 'before' with a ``rule_id`` as its value to make the new rule the
Use 'before' with a `rule_id` as its value to make the new rule the
next-most important rule with respect to the given user defined rule.
It is not possible to add a rule relative to a predefined server rule.
- in: query
@ -418,7 +418,7 @@ paths:
name: pushrule
description: |-
The push rule data. Additional top-level keys may be present depending
on the parameters for the rule ``kind``.
on the parameters for the rule `kind`.
required: true
schema:
type: object
@ -440,14 +440,14 @@ paths:
description: |-
The conditions that must hold true for an event in order for a
rule to be applied to an event. A rule with no conditions
always matches. Only applicable to ``underride`` and ``override`` rules.
always matches. Only applicable to `underride` and `override` rules.
items:
type: object
allOf: [ "$ref": "definitions/push_condition.yaml" ]
pattern:
type: string
description: |-
Only applicable to ``content`` rules. The glob-style pattern to match against.
Only applicable to `content` rules. The glob-style pattern to match against.
required: ["actions"]
responses:
200:
@ -497,8 +497,8 @@ paths:
required: true
x-example: "global"
description: |-
Either ``global`` or ``device/<profile_tag>`` to specify global
rules or device rules for the given ``profile_tag``.
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
- in: path
type: string
name: kind
@ -554,7 +554,7 @@ paths:
required: true
x-example: "global"
description: |-
``global`` to specify global rules.
`global` to specify global rules.
- in: path
type: string
name: kind
@ -620,8 +620,8 @@ paths:
required: true
x-example: "global"
description: |-
Either ``global`` or ``device/<profile_tag>`` to specify global
rules or device rules for the given ``profile_tag``.
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
- in: path
type: string
name: kind
@ -685,7 +685,7 @@ paths:
required: true
x-example: "global"
description: |-
``global`` to specify global rules.
`global` to specify global rules.
- in: path
type: string
name: kind

2
data/api/client-server/read_markers.yaml
Unescape Escape View File

@ -60,7 +60,7 @@ paths:
type: string
description: |-
The event ID to set the read receipt location at. This is
equivalent to calling ``/receipt/m.read/$elsewhere:example.org``
equivalent to calling `/receipt/m.read/$elsewhere:example.org`
and is provided here to save that extra call.
example: "$elsewhere:example.org"
required: ['m.fully_read']

4
data/api/client-server/receipts.yaml
Unescape Escape View File

@ -59,8 +59,8 @@ paths:
- in: body
name: receipt
description: |-
Extra receipt information to attach to ``content`` if any. The
server will automatically set the ``ts`` field.
Extra receipt information to attach to `content` if any. The
server will automatically set the `ts` field.
schema:
type: object
example: {

4
data/api/client-server/redaction.yaml
Unescape Escape View File

@ -36,9 +36,9 @@ paths:
This cannot be undone.
Any user with a power level greater than or equal to the ``m.room.redaction``
Any user with a power level greater than or equal to the `m.room.redaction`
event power level may send redaction events in the room. If the user's power
level greater is also greater than or equal to the ``redact`` power level
level greater is also greater than or equal to the `redact` power level
of the room, the user may redact events sent by other users.
Server administrators may redact events sent by users on their server.

96
data/api/client-server/registration.yaml
Unescape Escape View File

@ -43,27 +43,27 @@ paths:
If registration is successful, this endpoint will issue an access token
the client can use to authorize itself in subsequent requests.
If the client does not supply a ``device_id``, the server must
If the client does not supply a `device_id`, the server must
auto-generate one.
The server SHOULD register an account with a User ID based on the
``username`` provided, if any. Note that the grammar of Matrix User ID
`username` provided, if any. Note that the grammar of Matrix User ID
localparts is restricted, so the server MUST either map the provided
``username`` onto a ``user_id`` in a logical manner, or reject
``username``\s which do not comply to the grammar, with
``M_INVALID_USERNAME``.
`username` onto a `user_id` in a logical manner, or reject
`username`\s which do not comply to the grammar, with
`M_INVALID_USERNAME`.
Matrix clients MUST NOT assume that localpart of the registered
``user_id`` matches the provided ``username``.
`user_id` matches the provided `username`.
The returned access token must be associated with the ``device_id``
The returned access token must be associated with the `device_id`
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
When registering a guest account, all parameters in the request body
with the exception of ``initial_device_display_name`` MUST BE ignored
by the server. The server MUST pick a ``device_id`` for the account
with the exception of `initial_device_display_name` MUST BE ignored
by the server. The server MUST pick a `device_id` for the account
regardless of input.
Any user ID returned by this API must conform to the grammar given in the
@ -81,7 +81,7 @@ paths:
enum:
- guest
- user
description: The kind of account to register. Defaults to ``user``.
description: The kind of account to register. Defaults to `user`.
- in: body
name: body
required: true
@ -94,7 +94,7 @@ paths:
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself.
authenticate the `register` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
@ -118,12 +118,12 @@ paths:
type: string
description: |-
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
inhibit_login:
type: boolean
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
login. Defaults to false.
example: false
@ -151,7 +151,7 @@ paths:
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
Required if the ``inhibit_login`` option is false.
Required if the `inhibit_login` option is false.
home_server:
type: string
description: |-
@ -159,22 +159,22 @@ paths:
been registered.
**Deprecated**. Clients should extract the server_name from
``user_id`` (by splitting at the first colon) if they require
it. Note also that ``homeserver`` is not spelt this way.
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
ID of the registered device. Will be the same as the
corresponding parameter in the request, if one was specified.
Required if the ``inhibit_login`` option is false.
Required if the `inhibit_login` option is false.
required: ['user_id']
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_USER_IN_USE`` : The desired user ID is already taken.
* ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name.
* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
* `M_USER_IN_USE` : The desired user ID is already taken.
* `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
* `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
claimed by an application service.
These errors may be returned at any stage of the registration process,
@ -200,7 +200,7 @@ paths:
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular ``kind`` of account is not
can be used to identify that a particular `kind` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
@ -251,12 +251,12 @@ paths:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server.
* `M_THREEPID_IN_USE` : The email address is already registered to an account on this server.
However, if the homeserver has the ability to send email, it is recommended that the server
instead send an email to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given email address
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.
examples:
application/json: {
@ -301,12 +301,12 @@ paths:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
* `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server.
However, if the homeserver has the ability to send SMS message, it is recommended that the server
instead send an SMS message to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given phone number
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.
examples:
application/json: {
@ -352,7 +352,7 @@ paths:
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
When `false`, the server can still take advantage of `the soft logout method <#soft-logout>`_
for the user's remaining devices.
example: true
auth:
@ -386,20 +386,20 @@ paths:
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
`/account/password` endpoint.
This API's parameters and response are identical to that of the
|/register/email/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given email address could be found. The server may instead send an
email to the given address prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
.. |/register/email/requestToken| replace:: `/register/email/requestToken`
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordEmail
@ -428,7 +428,7 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
@ -445,19 +445,19 @@ paths:
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
`/account/password` endpoint.
This API's parameters and response are identical to that of the
|/register/msisdn/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given phone number could be found. The server may instead send the SMS
to the given phone number prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the phone number itself, either by sending a
validation message itself or by using a service it has control over.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
.. |/register/msisdn/requestToken| replace:: `/register/msisdn/requestToken`
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordMSISDN
@ -486,7 +486,7 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
@ -511,7 +511,7 @@ paths:
The homeserver may change the flows available depending on whether a
valid access token is provided.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
Unlike other endpoints, this endpoint does not take an `id_access_token`
parameter because the homeserver is expected to sign the request to the
identity server instead.
security:
@ -533,11 +533,11 @@ paths:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the ``id_server``
If not provided, the homeserver MUST use the `id_server`
that was originally use to bind each identifier. If the
homeserver does not know which ``id_server`` that was,
it must return an ``id_server_unbind_result`` of
``no-support``.
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: "example.org"
responses:
200:
@ -552,12 +552,12 @@ paths:
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). ``success`` indicates
the user's 3PIDs from the identity server(s). `success` indicates
that all identifiers have been unbound from the identity server while
``no-support`` indicates that one or more identifiers failed to unbind
`no-support` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be ``success`` if the homeserver has no identifiers to unbind
must be `success` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
@ -612,15 +612,15 @@ paths:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be ``true`` when the server replies with 200 OK.
be `true` when the server replies with 200 OK.
400:
description: |-
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
* ``M_USER_IN_USE`` : The desired username is already taken.
* ``M_INVALID_USERNAME`` : The desired username is not a valid user name.
* ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace
* `M_USER_IN_USE` : The desired username is already taken.
* `M_INVALID_USERNAME` : The desired username is not a valid user name.
* `M_EXCLUSIVE` : The desired username is in the exclusive namespace
claimed by an application service.
examples:
application/json: {

8
data/api/client-server/room_initial_sync.yaml
Unescape Escape View File

@ -98,12 +98,12 @@ paths:
start:
type: string
description: |-
A token which correlates to the first value in ``chunk``.
A token which correlates to the first value in `chunk`.
Used for pagination.
end:
type: string
description: |-
A token which correlates to the last value in ``chunk``.
A token which correlates to the last value in `chunk`.
Used for pagination.
chunk:
type: array
@ -112,7 +112,7 @@ paths:
list of the most recent messages for this room. If
the user has left the room this will be the
messages that preceeded them leaving. This array
will consist of at most ``limit`` elements.
will consist of at most `limit` elements.
items:
type: object
title: RoomEvent
@ -135,7 +135,7 @@ paths:
type: string
enum: ["private", "public"]
description: |-
Whether this room is visible to the ``/publicRooms`` API
Whether this room is visible to the `/publicRooms` API
or not."
account_data:
type: array

14
data/api/client-server/room_state.yaml
Unescape Escape View File

@ -35,18 +35,18 @@ paths:
.. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
overwritten if `<room id>`, `<event type>` and `<state key>` all
match.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
``state_key``. Furthermore, ``POST`` is unsupported on state paths.
like other `PUT` paths because they cannot be differentiated from the
`state_key`. Furthermore, `POST` is unsupported on state paths.
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
`Room Events`_ for the `m.` event specification.
If the event type being sent is ``m.room.canonical_alias`` servers
If the event type being sent is `m.room.canonical_alias` servers
SHOULD ensure that any new aliases being listed in the event are valid
per their grammar/syntax and that they point to the room ID where the
state event is to be sent. Servers do not validate aliases which are
@ -116,10 +116,10 @@ paths:
Some example error codes include:
* ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``
* `M_INVALID_PARAMETER`: One or more aliases within the `m.room.canonical_alias`
event have invalid syntax.
* ``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.
schema:
$ref: "definitions/errors/error.yaml"

10
data/api/client-server/rooms.yaml
Unescape Escape View File

@ -31,7 +31,7 @@ paths:
get:
summary: Get a single event by event ID.
description: |-
Get a single event based on ``roomId/eventId``. You must have permission to
Get a single event based on `roomId/eventId`. You must have permission to
retrieve this event e.g. by being a member in the room for this event.
operationId: getOneRoomEvent
security:
@ -196,7 +196,7 @@ paths:
type: string
description: |-
The point in time (pagination token) to return members for in the room.
This token can be obtained from a ``prev_batch`` token returned for
This token can be obtained from a `prev_batch` token returned for
each room by the sync API. Defaults to the current state of the room,
as determined by the server.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
@ -213,9 +213,9 @@ paths:
- ban
description: |-
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*
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"
- in: query
name: not_membership
@ -267,7 +267,7 @@ paths:
summary: Gets the list of currently joined users and their profile data.
description:
This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.
This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server.
operationId: getJoinedMembersByRoom
parameters:
- in: path

22
data/api/client-server/search.yaml
Unescape Escape View File

@ -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
@ -104,7 +104,7 @@ paths:
enum: ["recent", "rank"]
description: |-
The order in which to search for results.
By default, this is ``"rank"``.
By default, this is `"rank"`.
event_context:
title: Include Event Context
type: object
@ -117,13 +117,13 @@ paths:
title: "Before limit"
description: |-
How many events before the result are
returned. By default, this is ``5``.
returned. By default, this is `5`.
after_limit:
type: integer
title: "After limit"
description: |-
How many events after the result are
returned. By default, this is ``5``.
returned. By default, this is `5`.
include_profile:
type: boolean
title: "Return profile information"
@ -131,7 +131,7 @@ paths:
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is ``false``.
By default, this is `false`.
include_state:
type: boolean
title: Include current state
@ -231,7 +231,7 @@ paths:
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.
additionalProperties:
type: object
@ -265,10 +265,10 @@ paths:
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``.
`include_state` key set with a value of `true`.
The ``string`` key is the room ID for which the ``State
Event`` array belongs to.
The `string` key is the room ID for which the `State
Event` array belongs to.
additionalProperties:
type: array
title: Room State
@ -281,8 +281,8 @@ paths:
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:
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

62
data/api/client-server/sync.yaml
Unescape Escape View File

@ -36,20 +36,20 @@ paths:
incremental deltas to the state, and to receive new messages.
*Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_
for more information. Lazy-loading members is only supported on a ``StateFilter``
for more information. Lazy-loading members is only supported on a `StateFilter`
for this endpoint. When lazy-loading is enabled, servers MUST include the
syncing user's own membership event when they join a room, or when the
full state of rooms is requested, to aid discovering the user's avatar &
displayname.
Further, like other members, the user's own membership event is eligible
for being considered redundant by the server. When a sync is ``limited``,
for being considered redundant by the server. When a sync is `limited`,
the server MUST return membership events for events in the gap
(between ``since`` and the start of the returned timeline), regardless
(between `since` and the start of the returned timeline), regardless
as to whether or not they are redundant. This ensures that joins/leaves
and profile changes which occur during the gap are not lost.
Note that the default behaviour of ``state`` is to include all membership
Note that the default behaviour of `state` is to include all membership
events, alongside other state, when lazy-loading is not enabled.
operationId: sync
security:
@ -61,7 +61,7 @@ paths:
description: |-
The ID of a filter created using the filter API or a filter JSON
object encoded as a string. The server will detect whether it is
an ID or a JSON object by whether the first character is a ``"{"``
an ID or a JSON object by whether the first character is a `"{"`
open brace. Passing the JSON inline is best suited to one off
requests. Creating a filter using the filter API is recommended for
clients that reuse the same filter multiple times, for example in
@ -82,16 +82,16 @@ paths:
Controls whether to include the full state for all rooms the user
is a member of.
If this is set to ``true``, then all state events will be returned,
even if ``since`` is non-empty. The timeline will still be limited
by the ``since`` parameter. In this case, the ``timeout`` parameter
If this is set to `true`, then all state events will be returned,
even if `since` is non-empty. The timeline will still be limited
by the `since` parameter. In this case, the `timeout` parameter
will be ignored and the query will return immediately, possibly with
an empty timeline.
If ``false``, and ``since`` is non-empty, only state which has
changed since the point indicated by ``since`` will be returned.
If `false`, and `since` is non-empty, only state which has
changed since the point indicated by `since` will be returned.
By default, this is ``false``.
By default, this is `false`.
x-example: "false"
- in: query
name: set_presence
@ -113,7 +113,7 @@ paths:
request. If no events (or other data) become available before this
time elapses, the server will return a response with empty fields.
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.
x-example: 30000
responses:
@ -127,8 +127,8 @@ paths:
next_batch:
type: string
description: |-
The batch token to supply in the ``since`` param of the next
``/sync`` request.
The batch token to supply in the `since` param of the next
`/sync` request.
rooms:
title: Rooms
type: object
@ -157,7 +157,7 @@ paths:
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
`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
@ -169,7 +169,7 @@ paths:
when there are less than 5 members to represent.
When lazy-loading room members is enabled, the membership
events for the heroes MUST be included in the ``state``,
events for the heroes MUST be included in the `state`,
unless they are redundant. When the list of users changes,
the server notifies the client by sending a fresh list of
heroes. If there are no changes since the last sync, this
@ -179,14 +179,14 @@ paths:
"m.joined_member_count":
type: integer
description: |-
The number of users with ``membership`` of ``join``,
The number of users with `membership` of `join`,
including the client's own user ID. If this field has
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``.
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:
@ -194,14 +194,14 @@ paths:
type: object
description: |-
Updates to the state, between the time indicated by
the ``since`` parameter, and the start of the
``timeline`` (or all state up to the start of the
``timeline``, if ``since`` is not given, or
``full_state`` is true).
the `since` parameter, and the start of the
`timeline` (or all state up to the start of the
`timeline`, if `since` is not given, or
`full_state` is true).
N.B. state updates for ``m.room.member`` events will
be incomplete if ``lazy_load_members`` is enabled in
the ``/sync`` filter, and only return the member events
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:
@ -264,17 +264,17 @@ paths:
type: object
description: |-
The state of a room that the user has been invited
to. These state events may only have the ``sender``,
``type``, ``state_key`` and ``content`` keys
to. These state events may only have the `sender`,
`type`, `state_key` and `content` keys
present. These events do not replace any state that
the client already has for the room, for example if
the client has archived the room. Instead the
client should keep two separate copies of the
state: the one from the ``invite_state`` and one
from the archived ``state``. If the client joins
state: the one from the `invite_state` and one
from the archived `state`. If the client joins
the room then the current state will be given as a
delta against the archived ``state`` not the
``invite_state``.
delta against the archived `state` not the
`invite_state`.
properties:
events:
description: The StrippedState events that form the invite state.

4
data/api/client-server/tags.yaml
Unescape Escape View File

@ -69,7 +69,7 @@ paths:
type: number
format: float
description: |-
A number in a range ``[0,1]`` describing a relative
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
examples:
@ -125,7 +125,7 @@ paths:
type: number
format: float
description: |-
A number in a range ``[0,1]`` describing a relative
A number in a range `[0,1]` describing a relative
position of the room under the given tag.
additionalProperties: true
example: {

10
data/api/client-server/third_party_membership.yaml
Unescape Escape View File

@ -48,7 +48,7 @@ paths:
join that room.
If the identity server did know the Matrix user identifier for the
third party identifier, the homeserver will append a ``m.room.member``
third party identifier, the homeserver will append a `m.room.member`
event to the room.
If the identity server does not know a Matrix user identifier for the
@ -56,7 +56,7 @@ paths:
which can be accepted upon providing proof of ownership of the third
party identifier. This is achieved by the identity server generating a
token, which it gives to the inviting homeserver. The homeserver will
add an ``m.room.third_party_invite`` event into the graph for the room,
add an `m.room.third_party_invite` event into the graph for the room,
containing that token.
When the invitee binds the invited third party identifier to a Matrix
@ -72,7 +72,7 @@ paths:
- The matrix user ID who invited them to the room
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.
.. _joining rooms section: `invite-by-user-id-endpoint`_
operationId: inviteBy3PID
@ -109,7 +109,7 @@ paths:
medium:
type: string
# TODO: Link to Identity Service spec when it eixsts
description: The kind of address being passed in the address field, for example ``email``.
description: The kind of address being passed in the address field, for example `email`.
address:
type: string
description: The invitee's third party identifier.
@ -124,7 +124,7 @@ paths:
type: object
403:
description: |-
You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
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:
- The invitee has been banned from the room.
- The invitee is already a member of the room.

6
data/api/client-server/typing.yaml
Unescape Escape View File

@ -32,8 +32,8 @@ paths:
summary: Informs the server that the user has started or stopped typing.
description: |-
This tells the server that the user is typing for the next N
milliseconds where N is the value specified in the ``timeout`` key.
Alternatively, if ``typing`` is ``false``, it tells the server that the
milliseconds where N is the value specified in the `timeout` key.
Alternatively, if `typing` is `false`, it tells the server that the
user has stopped typing.
operationId: setTyping
security:
@ -65,7 +65,7 @@ paths:
typing:
type: boolean
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.
timeout:
type: integer

4
data/api/client-server/users.yaml
Unescape Escape View File

@ -39,8 +39,8 @@ paths:
query remote users as part of the search.
The search is performed case-insensitively on user IDs and display
names preferably using a collation determined based upon the
``Accept-Language`` header provided in the request, if present.
names preferably using a collation determined based upon the
`Accept-Language` header provided in the request, if present.
operationId: searchUserDirectory
security:
- accessToken: []

8
data/api/client-server/versions.yaml
Unescape Escape View File

@ -29,13 +29,13 @@ paths:
description: |-
Gets the versions of the specification supported by the server.
Values will take the form ``rX.Y.Z``.
Values will take the form `rX.Y.Z`.
Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
Only the latest `Z` value will be reported for each supported `X.Y` value.
i.e. if the server implements `r0.0.0`, `r0.0.1`, and `r1.2.0`, it will report `r0.0.1` and `r1.2.0`.
The server may additionally advertise experimental features it supports
through ``unstable_features``. These features should be namespaced and
through `unstable_features`. These features should be namespaced and
may optionally include version information within their name if desired.
Features listed here are not for optionally toggling parts of the Matrix
specification and should only be used to advertise support for a feature

2
data/api/client-server/wellknown.yaml
Unescape Escape View File

@ -28,7 +28,7 @@ paths:
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
e.g. `com.example.myapp.property`. This ensures property names are
suitably namespaced for each application and reduces the risk of
clashes.

14
data/api/client-server/whoami.yaml
Unescape Escape View File

@ -29,13 +29,13 @@ paths:
get:
summary: Gets information about the owner of an access token.
description: |-
Gets information about the owner of a given access token.
Note that, as with the rest of the Client-Server API,
Application Services may masquerade as users within their
namespace by giving a ``user_id`` query parameter. In this
situation, the server should verify that the given ``user_id``
is registered by the appservice, and return it in the response
Gets information about the owner of a given access token.
Note that, as with the rest of the Client-Server API,
Application Services may masquerade as users within their
namespace by giving a `user_id` query parameter. In this
situation, the server should verify that the given `user_id`
is registered by the appservice, and return it in the response
body.
operationId: getTokenOwner
security:

38
data/api/identity/associations.yaml
Unescape Escape View File

@ -35,13 +35,13 @@ paths:
- in: query
type: string
name: sid
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
required: true
x-example: 1234
- in: query
type: string
name: client_secret
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
@ -72,9 +72,9 @@ paths:
description: |-
The session has not been validated.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
@ -97,12 +97,12 @@ paths:
description: |-
Publish an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session\'s 3pids will return
Future calls to `/lookup` for any of the session\'s 3pids will return
this association.
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: bind
deprecated: true
@ -119,10 +119,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
@ -184,9 +184,9 @@ paths:
description: |-
The association was not published.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
@ -209,15 +209,15 @@ paths:
description: |-
Remove an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session's 3pids will not
Future calls to `/lookup` for any of the session's 3pids will not
return the removed association.
The identity server should authenticate the request in one of two
ways:
1. The request is signed by the homeserver which controls the ``user_id``.
2. The request includes the ``sid`` and ``client_secret`` parameters,
as per ``/3pid/bind``, which proves ownership of the 3PID.
1. The request is signed by the homeserver which controls the `user_id`.
2. The request includes the `sid` and `client_secret` parameters,
as per `/3pid/bind`, which proves ownership of the 3PID.
If this endpoint returns a JSON Matrix error, that error should be passed
through to the client requesting an unbind through a homeserver, if the
@ -241,10 +241,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
@ -253,7 +253,7 @@ paths:
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using ``sid`` and ``client_secret`` to authenticate this request.
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string

6
data/api/identity/definitions/request_email_validation.yaml
Unescape Escape View File

@ -23,7 +23,7 @@ properties:
description: |
A unique string generated by the client, and used to identify the
validation attempt. It must be a string consisting of the characters
``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it
must not be empty.
example: "monkeys_are_GREAT"
email:
@ -33,9 +33,9 @@ properties:
send_attempt:
type: integer
description: |-
The server will only send an email if the ``send_attempt``
The server will only send an email if the `send_attempt`
is a number greater than the most recent one which it has seen,
scoped to that ``email`` + ``client_secret`` pair. This is to
scoped to that `email` + `client_secret` pair. This is to
avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity server.
The client should increment this value if they desire a new

8
data/api/identity/definitions/request_msisdn_validation.yaml
Unescape Escape View File

@ -24,14 +24,14 @@ properties:
description: |
A unique string generated by the client, and used to identify the
validation attempt. It must be a string consisting of the characters
``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it
must not be empty.
example: "monkeys_are_GREAT"
country:
type: string
description: |-
The two-letter uppercase ISO-3166-1 alpha-2 country code that the
number in ``phone_number`` should be parsed as if it were dialled from.
number in `phone_number` should be parsed as if it were dialled from.
example: "GB"
phone_number:
type: string
@ -40,9 +40,9 @@ properties:
send_attempt:
type: integer
description: |-
The server will only send an SMS if the ``send_attempt`` is a
The server will only send an SMS if the `send_attempt` is a
number greater than the most recent one which it has seen,
scoped to that ``country`` + ``phone_number`` + ``client_secret``
scoped to that `country` + `phone_number` + `client_secret`
triple. This is to avoid repeatedly sending the same SMS in
the case of request retries between the POSTing user and the
identity server. The client should increment this value if

2
data/api/identity/definitions/security.yaml
Unescape Escape View File

@ -13,6 +13,6 @@
# limitations under the License.
accessToken:
type: apiKey
description: The access_token returned by a call to ``/register``.
description: The access_token returned by a call to `/register`.
name: access_token
in: query

2
data/api/identity/definitions/sid.yaml
Unescape Escape View File

@ -18,7 +18,7 @@ properties:
description: |
The session ID. Session IDs are opaque strings generated by the identity
server. They must consist entirely of the characters
``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they
`[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they
must not be empty.
example: "123abc"
required: ['sid']

36
data/api/identity/email_associations.yaml
Unescape Escape View File

@ -37,13 +37,13 @@ paths:
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
`/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 previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailRequestToken
deprecated: true
@ -61,8 +61,8 @@ paths:
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.
- `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",
@ -77,10 +77,10 @@ paths:
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
@ -90,7 +90,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPost
deprecated: true
@ -107,13 +107,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
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:
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 user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -136,10 +136,10 @@ paths:
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
@ -150,28 +150,28 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
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
- in: query
type: string
name: token
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 user.
x-example: atoken
responses:
200:
description: Email address is validated.
"3xx":
description: |-
Email address is validated, and the ``next_link`` parameter was
provided to the ``requestToken`` call. The user must be redirected
to the URL provided by the ``next_link`` parameter.
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.

6
data/api/identity/invitation_signing.yaml
Unescape Escape View File

@ -30,8 +30,8 @@ paths:
description: |-
Sign invitation details.
The identity server will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
The identity server will look up `token` which was stored in a call
to `store-invite`, and fetch the sender of the invite.
operationId: blindlySignStuff
deprecated: true
parameters:
@ -50,7 +50,7 @@ paths:
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The 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`_.

8
data/api/identity/lookup.yaml
Unescape Escape View File

@ -131,8 +131,8 @@ paths:
- 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.
An array of arrays containing the `3PID Types`_ with the `medium`
in first position and the `address` in second position.
required:
- "threepids"
responses:
@ -164,8 +164,8 @@ paths:
- 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
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"

38
data/api/identity/phone_associations.yaml
Unescape Escape View File

@ -37,13 +37,13 @@ paths:
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
`/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 previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestToken
deprecated: true
@ -61,9 +61,9 @@ paths:
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 server cannot deliver an
- `M_INVALID_ADDRESS`: The phone number provided was invalid.
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
@ -79,10 +79,10 @@ paths:
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number is considered to
`requestToken` call, ownership of the phone number is considered to
have been validated. This does not publish any information publicly, or
associate the phone number address with any Matrix user
ID. Specifically, calls to ``/lookup`` will not show a binding.
ID. Specifically, calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
@ -92,7 +92,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPost
deprecated: true
@ -109,13 +109,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
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:
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 user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -138,10 +138,10 @@ paths:
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number address is
`requestToken` call, ownership of the phone number address is
considered to have been validated. This does not publish any
information publicly, or associate the phone number with any Matrix
user ID. Specifically, calls to ``/lookup`` will not show a binding.
user ID. Specifically, calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
@ -152,28 +152,28 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
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
- in: query
type: string
name: token
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
responses:
200:
description: Phone number is validated.
"3xx":
description: |-
Phone number address is validated, and the ``next_link`` parameter
was provided to the ``requestToken`` call. The user must be
redirected to the URL provided by the ``next_link`` parameter.
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.

32
data/api/identity/store_invite.yaml
Unescape Escape View File

@ -37,23 +37,23 @@ paths:
The service will generate a random token and an ephemeral key used for
accepting the invite.
The service also generates a ``display_name`` for the inviter, which is
a redacted version of ``address`` which does not leak the full contents
of the ``address``.
The service also generates a `display_name` for the inviter, which is
a redacted version of `address` which does not leak the full contents
of the `address`.
The service records persistently all of the above information.
It also generates an email containing all of this data, sent to the
``address`` parameter, notifying them of the invitation.
`address` parameter, notifying them of the invitation.
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
requests to `/_matrix/identity/api/v1/pubkey/ephemeral/isvalid`.
Currently, invites may only be issued for 3pids of the ``email`` medium.
Currently, invites may only be issued for 3pids of the `email` medium.
Optional fields in the request should be populated to the best of the
server's ability. Identity servers may use these variables when notifying
the ``address`` of the pending invite for display purposes.
the `address` of the pending invite for display purposes.
operationId: storeInvite
deprecated: true
parameters:
@ -64,7 +64,7 @@ paths:
properties:
medium:
type: string
description: The literal string ``email``.
description: The literal string `email`.
example: "email"
address:
type: string
@ -82,26 +82,26 @@ paths:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the ``m.room.canonical_alias``
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the ``m.room.avatar`` state event.
be retrieved from the `m.room.avatar` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The ``join_rule`` for the room to which the user is invited. This should
be retrieved from the ``m.room.join_rules`` state event.
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the ``m.room.name`` state event.
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
@ -122,7 +122,7 @@ paths:
type: string
description: |
The generated token. Must be a string consisting of the
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
@ -149,8 +149,8 @@ paths:
An error has occured.
If the 3pid is already bound to a Matrix user ID, the error code
will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the
error code will be ``M_UNRECOGNIZED``.
will be `M_THREEPID_IN_USE`. If the medium is unsupported, the
error code will be `M_UNRECOGNIZED`.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",

44
data/api/identity/v2_associations.yaml
Unescape Escape View File

@ -39,13 +39,13 @@ paths:
- in: query
type: string
name: sid
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
required: true
x-example: 1234
- in: query
type: string
name: client_secret
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
@ -76,9 +76,9 @@ paths:
description: |-
The session has not been validated.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
@ -98,7 +98,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -112,12 +112,12 @@ paths:
description: |-
Publish an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session\'s 3pids will return
Future calls to `/lookup` for any of the session\'s 3pids will return
this association.
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: bindV2
security:
@ -135,10 +135,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
@ -200,9 +200,9 @@ paths:
description: |-
The association was not published.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
@ -222,7 +222,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -236,15 +236,15 @@ paths:
description: |-
Remove an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session's 3pids will not
Future calls to `/lookup` for any of the session's 3pids will not
return the removed association.
The identity server should authenticate the request in one of two
ways:
1. The request is signed by the homeserver which controls the ``user_id``.
2. The request includes the ``sid`` and ``client_secret`` parameters,
as per ``/3pid/bind``, which proves ownership of the 3PID.
1. The request is signed by the homeserver which controls the `user_id`.
2. The request includes the `sid` and `client_secret` parameters,
as per `/3pid/bind`, which proves ownership of the 3PID.
If this endpoint returns a JSON Matrix error, that error should be passed
through to the client requesting an unbind through a homeserver, if the
@ -269,10 +269,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
@ -281,7 +281,7 @@ paths:
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using ``sid`` and ``client_secret`` to authenticate this request.
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
@ -317,7 +317,7 @@ paths:
the chosen authentication method (such as blocking homeservers from
unbinding identifiers).
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`_ in order to continue.
examples:
application/json: {

6
data/api/identity/v2_auth.yaml
Unescape Escape View File

@ -32,7 +32,7 @@ paths:
description: |-
Exchanges an OpenID token from the homeserver for an access token to
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
parameters:
- in: body
@ -83,7 +83,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -121,7 +121,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

42
data/api/identity/v2_email_associations.yaml
Unescape Escape View File

@ -40,13 +40,13 @@ paths:
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
`/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 previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailRequestTokenV2
security:
@ -65,8 +65,8 @@ paths:
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.
- `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",
@ -77,7 +77,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -92,10 +92,10 @@ paths:
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
@ -105,7 +105,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPostV2
security:
@ -123,13 +123,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
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:
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 user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -149,7 +149,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -163,10 +163,10 @@ paths:
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
@ -178,35 +178,35 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
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
- in: query
type: string
name: token
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 user.
x-example: atoken
responses:
200:
description: Email address is validated.
"3xx":
description: |-
Email address is validated, and the ``next_link`` parameter was
provided to the ``requestToken`` call. The user must be redirected
to the URL provided by the ``next_link`` parameter.
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

8
data/api/identity/v2_invitation_signing.yaml
Unescape Escape View File

@ -33,8 +33,8 @@ paths:
description: |-
Sign invitation details.
The identity server will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
The identity server will look up `token` which was stored in a call
to `store-invite`, and fetch the sender of the invite.
operationId: blindlySignStuffV2
security:
- accessToken: []
@ -54,7 +54,7 @@ paths:
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The 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`_.
@ -102,7 +102,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

28
data/api/identity/v2_lookup.yaml
Unescape Escape View File

@ -55,7 +55,7 @@ paths:
type: string
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the ``/lookup`` endpoint when performing lookups.
supply to the `/lookup` endpoint when performing lookups.
Servers SHOULD rotate this string often.
algorithms:
@ -63,7 +63,7 @@ paths:
items:
type: string
description: |-
The algorithms the server supports. Must contain at least ``sha256``.
The algorithms the server supports. Must contain at least `sha256`.
required: ['lookup_pepper', 'algorithms']
"/lookup":
post:
@ -84,14 +84,14 @@ paths:
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``.
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.
The pepper from `/hash_details`. This is required even when the
`algorithm` does not make use of it.
example: "matrixrocks"
addresses:
type: array
@ -99,7 +99,7 @@ paths:
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
the `algorithm` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
example: [
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
@ -109,7 +109,7 @@ paths:
responses:
200:
description:
The associations for any matched ``addresses``.
The associations for any matched `addresses`.
examples:
application/json: {
"mappings": {
@ -122,7 +122,7 @@ paths:
mappings:
type: object
description: |-
Any applicable mappings of ``addresses`` to Matrix User IDs. Addresses
Any applicable mappings of `addresses` to Matrix User IDs. Addresses
which do not have associations will not be included, which can make
this property be an empty object.
title: AssociatedMappings
@ -132,13 +132,13 @@ paths:
400:
description:
The client's request was invalid in some way. One possible problem could
be the ``pepper`` being invalid after the server has rotated it - this is
presented with the ``M_INVALID_PEPPER`` error code. Clients SHOULD make
a call to ``/hash_details`` to get a new pepper in this scenario, being
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.
`M_INVALID_PARAM` can also be returned to indicate the client supplied
an `algorithm` that is unknown to the server.
examples:
application/json: {
"errcode": "M_INVALID_PEPPER",

44
data/api/identity/v2_phone_associations.yaml
Unescape Escape View File

@ -40,13 +40,13 @@ paths:
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
`/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 previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestTokenV2
security:
@ -65,9 +65,9 @@ paths:
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 server cannot deliver an
- `M_INVALID_ADDRESS`: The phone number provided was invalid.
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
@ -79,7 +79,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -94,10 +94,10 @@ paths:
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number is considered to
`requestToken` call, ownership of the phone number is considered to
have been validated. This does not publish any information publicly, or
associate the phone number address with any Matrix user
ID. Specifically, calls to ``/lookup`` will not show a binding.
ID. Specifically, calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
@ -107,7 +107,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPostV2
security:
@ -125,13 +125,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
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:
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 user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -151,7 +151,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -165,10 +165,10 @@ paths:
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number address is
`requestToken` call, ownership of the phone number address is
considered to have been validated. This does not publish any
information publicly, or associate the phone number with any Matrix
user ID. Specifically, calls to ``/lookup`` will not show a binding.
user ID. Specifically, calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
@ -180,35 +180,35 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
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
- in: query
type: string
name: token
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
responses:
200:
description: Phone number is validated.
"3xx":
description: |-
Phone number address is validated, and the ``next_link`` parameter
was provided to the ``requestToken`` call. The user must be
redirected to the URL provided by the ``next_link`` parameter.
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

34
data/api/identity/v2_store_invite.yaml
Unescape Escape View File

@ -40,23 +40,23 @@ paths:
The service will generate a random token and an ephemeral key used for
accepting the invite.
The service also generates a ``display_name`` for the inviter, which is
a redacted version of ``address`` which does not leak the full contents
of the ``address``.
The service also generates a `display_name` for the inviter, which is
a redacted version of `address` which does not leak the full contents
of the `address`.
The service records persistently all of the above information.
It also generates an email containing all of this data, sent to the
``address`` parameter, notifying them of the invitation.
`address` parameter, notifying them of the invitation.
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``.
requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
Currently, invites may only be issued for 3pids of the ``email`` medium.
Currently, invites may only be issued for 3pids of the `email` medium.
Optional fields in the request should be populated to the best of the
server's ability. Identity servers may use these variables when notifying
the ``address`` of the pending invite for display purposes.
the `address` of the pending invite for display purposes.
operationId: storeInviteV2
security:
- accessToken: []
@ -68,7 +68,7 @@ paths:
properties:
medium:
type: string
description: The literal string ``email``.
description: The literal string `email`.
example: "email"
address:
type: string
@ -86,26 +86,26 @@ paths:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the ``m.room.canonical_alias``
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the ``m.room.avatar`` state event.
be retrieved from the `m.room.avatar` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The ``join_rule`` for the room to which the user is invited. This should
be retrieved from the ``m.room.join_rules`` state event.
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the ``m.room.name`` state event.
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
@ -126,7 +126,7 @@ paths:
type: string
description: |
The generated token. Must be a string consisting of the
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
@ -153,8 +153,8 @@ paths:
An error has occured.
If the 3pid is already bound to a Matrix user ID, the error code
will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the
error code will be ``M_UNRECOGNIZED``.
will be `M_THREEPID_IN_USE`. If the medium is unsupported, the
error code will be `M_UNRECOGNIZED`.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
@ -166,7 +166,7 @@ paths:
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`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

4
data/api/identity/v2_terms.yaml
Unescape Escape View File

@ -106,7 +106,7 @@ paths:
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.
have already added that URL to the `m.accepted_terms` collection.
required: ['name', 'url']
required: ['policies']
post:
@ -121,7 +121,7 @@ paths:
to the user. Servers SHOULD consider acceptance of any one language's URL as
acceptance for all other languages of that policy.
The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client
The server should avoid returning `M_TERMS_NOT_SIGNED` because the client
may not be accepting all terms at once.
operationId: agreeToTerms
security:

16
data/api/push-gateway/push_notifier.yaml
Unescape Escape View File

@ -39,7 +39,7 @@ paths:
Notifications about a particular event will normally cause the user to be
alerted in some way. It is therefore necessary to perform duplicate
suppression for such notifications using the ``event_id`` field to avoid
suppression for such notifications using the `event_id` field to avoid
retries of this HTTP API causing duplicate alerts. The operation of
updating counts of unread notifications should be idempotent and
therefore do not require duplicate suppression.
@ -111,7 +111,7 @@ paths:
type:
type: string
description: |-
The type of the event as in the event's ``type`` field.
The type of the event as in the event's `type` field.
sender:
type: string
description: |-
@ -131,13 +131,13 @@ paths:
type: boolean
description: |-
This is true if the user receiving the notification is the
subject of a member event (i.e. the ``state_key`` of the
subject of a member event (i.e. the `state_key` of the
member event is equal to the user's Matrix ID).
prio:
type: string
enum: ["high", "low"]
description: |-
The priority of the notification. If omitted, ``high`` is
The priority of the notification. If omitted, `high` is
assumed. This may be used by push gateways to deliver less
time-sensitive notifications in a way that will preserve
battery power on mobile devices.
@ -145,7 +145,7 @@ paths:
type: object
title: EventContent
description: |-
The ``content`` field from the event, if present. The pusher
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:
@ -178,10 +178,10 @@ paths:
app_id:
type: string
description: |-
The ``app_id`` given when the pusher was created.
The `app_id` given when the pusher was created.
pushkey:
type: string
description: The ``pushkey`` given when the pusher was created.
description: The `pushkey` given when the pusher was created.
pushkey_ts:
type: integer
description: |-
@ -193,7 +193,7 @@ paths:
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.
pusher creation minus the `url` key.
tweaks:
type: object
title: Tweaks

18
data/api/server-server/backfill.yaml
Unescape Escape View File

@ -32,8 +32,8 @@ paths:
summary: Retrieves the events which precede the given event
description: |-
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs given in ``v`` and
the PDUs that preceded them are retrieved, up to the total number given by the ``limit``.
Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and
the PDUs that preceded them are retrieved, up to the total number given by the `limit`.
operationId: backfillRoom
security:
- signedRequest: []
@ -65,12 +65,12 @@ paths:
event(s), up to the given limit.
**Note:**
Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited
Though the PDU definitions require that `prev_events` and `auth_events` be limited
in number, the response of backfill MUST NOT be validated on these specific restrictions.
Due to historical reasons, it is possible that events which were previously accepted
would now be rejected by these limitations. The events should be rejected per usual by
the ``/send``, ``/get_missing_events``, and remaining endpoints.
the `/send`, `/get_missing_events`, and remaining endpoints.
schema:
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
@ -78,8 +78,8 @@ paths:
summary: Retrieves events that the sender is missing
description: |-
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
and stopping at the ``limit``.
walk of the `prev_events` for the `latest_events`, ignoring any events in `earliest_events`
and stopping at the `limit`.
operationId: getMissingPreviousEvents
security:
- signedRequest: []
@ -107,7 +107,7 @@ paths:
type: array
description: |-
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of ``latest_events``.
the previous events of `latest_events`.
items:
type: string
example: ["$missing_event:example.org"]
@ -121,8 +121,8 @@ paths:
responses:
200:
description: |-
The previous events for ``latest_events``, excluding any ``earliest_events``, up to the
provided ``limit``.
The previous events for `latest_events`, excluding any `earliest_events`, up to the
provided `limit`.
schema:
type: object
properties:

6
data/api/server-server/definitions/event-schemas/m.device_list_update.yaml
Unescape Escape View File

@ -32,7 +32,7 @@ allOf:
edu_type:
type: enum
enum: ['m.device_list_update']
description: The string ``m.device_list_update``.
description: The string `m.device_list_update`.
example: "m.device_list_update"
content:
type: object
@ -57,7 +57,7 @@ allOf:
type: integer
description: |-
An ID sent by the server for this update, unique for a given
user_id. Used to identify any gaps in the sequence of ``m.device_list_update``
user_id. Used to identify any gaps in the sequence of `m.device_list_update`
EDUs broadcast by a server.
example: 6
prev_id:
@ -67,7 +67,7 @@ allOf:
which have not been referred to already in an EDU's prev_id field. If the
receiving server does not recognise any of the prev_ids, it means an EDU
has been lost and the server should query a snapshot of the device list
via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update``
via `/user/keys/query` in order to correctly interpret future `m.device_list_update`
EDUs. May be missing or empty for the first EDU in a sequence.
items:
type: integer

4
data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml
Unescape Escape View File

@ -25,7 +25,7 @@ allOf:
edu_type:
type: enum
enum: ['m.direct_to_device']
description: The string ``m.direct_to_device``.
description: The string `m.direct_to_device`.
example: "m.direct_to_device"
content:
type: object
@ -50,7 +50,7 @@ allOf:
description: |-
The contents of the messages to be sent. These are arranged in
a map of user IDs to a map of device IDs to message bodies.
The device ID may also be ``*``, meaning all known devices for the user.
The device ID may also be `*`, meaning all known devices for the user.
additionalProperties:
type: object
title: User Devices

6
data/api/server-server/definitions/event-schemas/m.presence.yaml
Unescape Escape View File

@ -23,7 +23,7 @@ allOf:
edu_type:
type: enum
enum: ['m.presence']
description: The string ``m.presence``
description: The string `m.presence`
example: "m.presence"
content:
type: object
@ -63,8 +63,8 @@ allOf:
type: boolean
description: |-
True if the user is likely to be interacting with their
client. This may be indicated by the user having a
``last_active_ago`` within the last few minutes. Defaults
client. This may be indicated by the user having a
`last_active_ago` within the last few minutes. Defaults
to false.
example: true
required: ['user_id', 'presence', 'last_active_ago']

2
data/api/server-server/definitions/event-schemas/m.receipt.yaml
Unescape Escape View File

@ -26,7 +26,7 @@ allOf:
edu_type:
type: enum
enum: ['m.receipt']
description: The string ``m.receipt``
description: The string `m.receipt`
example: "m.receipt"
content:
type: object

2
data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
Unescape Escape View File

@ -24,7 +24,7 @@ allOf:
edu_type:
type: enum
enum: ['m.signing_key_update']
description: The string ``m.signing_update``.
description: The string `m.signing_update`.
example: "m.signing_key_update"
content:
type: object

2
data/api/server-server/definitions/event-schemas/m.typing.yaml
Unescape Escape View File

@ -22,7 +22,7 @@ allOf:
edu_type:
type: enum
enum: ['m.typing']
description: The string ``m.typing``
description: The string `m.typing`
example: "m.typing"
content:
type: object

8
data/api/server-server/definitions/invite_event.yaml
Unescape Escape View File

@ -22,7 +22,7 @@ allOf:
sender:
type: string
description: |-
The matrix ID of the user who sent the original ``m.room.third_party_invite``.
The matrix ID of the user who sent the original `m.room.third_party_invite`.
example: "@someone:example.org"
origin:
type: string
@ -35,7 +35,7 @@ allOf:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -46,12 +46,12 @@ allOf:
title: Membership Event Content
description: |-
The content of the event, matching what is available in the
`Client-Server API`_. Must include a ``membership`` of ``invite``.
`Client-Server API`_. Must include a `membership` of `invite`.
example: {"membership": "invite"}
properties:
membership:
type: string
description: The value ``invite``.
description: The value `invite`.
example: "invite"
required: ['membership']
required:

14
data/api/server-server/definitions/keys.yaml
Unescape Escape View File

@ -26,10 +26,10 @@ properties:
description: |-
Public keys of the homeserver for verifying digital signatures.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``abc123`` being the version in the example below). Together,
The object's key is the algorithm and version combined (`ed25519` being the
algorithm and `abc123` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Verify Key
@ -49,10 +49,10 @@ properties:
description: |-
The public keys that the server used to use and when it stopped using them.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``0ldK3y`` being the version in the example below). Together,
The object's key is the algorithm and version combined (`ed25519` being the
algorithm and `0ldK3y` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Old Verify Key
@ -76,7 +76,7 @@ properties:
signatures:
type: object
description: |-
Digital signatures for this object signed using the ``verify_keys``.
Digital signatures for this object signed using the `verify_keys`.
The signature is calculated using the process described at `Signing
JSON`_.

2
data/api/server-server/definitions/security.yaml
Unescape Escape View File

@ -14,6 +14,6 @@
signedRequest:
type: apiKey
description: |-
The ``Authorization`` header defined in the `Authentication`_ section.
The `Authorization` header defined in the `Authentication`_ section.
name: Authorization
in: header

2
data/api/server-server/definitions/transaction.yaml
Unescape Escape View File

@ -20,7 +20,7 @@ properties:
origin:
type: string
description: |-
The ``server_name`` of the homeserver sending this transaction.
The `server_name` of the homeserver sending this transaction.
example: "example.org"
origin_server_ts:
type: integer

8
data/api/server-server/definitions/unsigned_pdu_base.yaml
Unescape Escape View File

@ -27,7 +27,7 @@ properties:
example: "@someone:matrix.org"
origin:
type: string
description: The ``server_name`` of the homeserver that created this event.
description: The `server_name` of the homeserver that created this event.
example: "matrix.org"
origin_server_ts:
type: integer
@ -42,7 +42,7 @@ properties:
type: string
description: |-
If this key is present, the event is a state event, and it will replace previous events
with the same ``type`` and ``state_key`` in the room state.
with the same `type` and `state_key` in the room state.
example: "my_key"
content:
type: object
@ -77,7 +77,7 @@ properties:
depth:
type: integer
description: |-
The maximum depth of the ``prev_events``, plus one. Must be less than the
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
@ -117,7 +117,7 @@ properties:
type: object
title: UnsignedData
description: |-
Additional data added by the origin server but not covered by the ``signatures``. More
Additional data added by the origin server but not covered by the `signatures`. More
keys than those defined here may be used.
example: {"key": "value"}
properties:

2
data/api/server-server/events.yaml
Unescape Escape View File

@ -94,7 +94,7 @@ paths:
summary: Get all the state event IDs of a given room
description: |-
Retrieves a snapshot of a room's state at a given event, in the form of
event IDs. This performs the same function as calling ``/state/{roomId}``,
event IDs. This performs the same function as calling `/state/{roomId}`,
however this returns just the event IDs rather than the full events.
operationId: getRoomStateIds
security:

6
data/api/server-server/invites-v1.yaml
Unescape Escape View File

@ -36,8 +36,8 @@ paths:
room by the inviting homeserver.
Servers should prefer to use the v2 API for invites instead of the v1 API. Servers
which receive a v1 invite request must assume that the room version is either ``"1"``
or ``"2"``.
which receive a v1 invite request must assume that the room version is either `"1"`
or `"2"`.
Note that events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The request and response
@ -113,7 +113,7 @@ paths:
maxItems: 2
items:
- type: integer
description: The value ``200``.
description: The value `200`.
example: 200
- type: object
description: An object containing the signed invite event.

6
data/api/server-server/invites-v2.yaml
Unescape Escape View File

@ -164,7 +164,7 @@ paths:
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
to join has a version that is not listed in the `ver`
parameters.
The error should be passed through to clients so that they
@ -177,8 +177,8 @@ paths:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",

20
data/api/server-server/joins-v1.yaml
Unescape Escape View File

@ -57,7 +57,7 @@ paths:
name: ver
description: |-
The room versions the sending server has support for. Defaults
to ``[1]``.
to `[1]`.
x-example: ["1", "2"]
responses:
200:
@ -99,7 +99,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -113,7 +113,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:
@ -141,7 +141,7 @@ paths:
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
to join has a version that is not listed in the `ver`
parameters.
The error should be passed through to clients so that they
@ -154,8 +154,8 @@ paths:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
@ -177,7 +177,7 @@ paths:
summary: Submit a signed join event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 ``/send_join`` endpoint.
Servers should instead prefer to use the v2 `/send_join` endpoint.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
@ -224,7 +224,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -238,7 +238,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:
@ -269,7 +269,7 @@ paths:
maxItems: 2
items:
- type: integer
description: The value ``200``.
description: The value `200`.
example: 200
- $ref: "./definitions/send_join_response.yaml"
examples:

4
data/api/server-server/joins-v2.yaml
Unescape Escape View File

@ -87,7 +87,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -101,7 +101,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:

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

Write Preview
Loading…
Cancel
Save