wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Change RST code formatting markup to Markdown

Browse source
This commit is contained in:
Will 2021-01-27 12:14:31 -08:00 • committed by Richard van der Hoff
parent c7cf90abfa
commit 27f8867aa0
158 changed files with 931 additions and 931 deletions
Download patch file Download diff file Expand all files Collapse all files

4
data/api/client-server/account-data.yaml
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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: