mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
649 lines
22 KiB
YAML
649 lines
22 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Push Rules API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/pushrules/":
|
|
get:
|
|
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.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: All the push rulesets for this user.
|
|
schema:
|
|
type: object
|
|
required: ["global"]
|
|
properties:
|
|
global:
|
|
type: object
|
|
description: The global ruleset.
|
|
title: Ruleset
|
|
allOf: [
|
|
"$ref": "definitions/push_ruleset.yaml"
|
|
]
|
|
examples:
|
|
application/json: {
|
|
"global": {
|
|
"content": [
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "sound",
|
|
"value": "default"
|
|
},
|
|
{
|
|
"set_tweak": "highlight"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"pattern": "alice",
|
|
"rule_id": ".m.rule.contains_user_name"
|
|
}
|
|
],
|
|
"override": [
|
|
{
|
|
"actions": [
|
|
"dont_notify"
|
|
],
|
|
"conditions": [],
|
|
"default": true,
|
|
"enabled": false,
|
|
"rule_id": ".m.rule.master"
|
|
},
|
|
{
|
|
"actions": [
|
|
"dont_notify"
|
|
],
|
|
"conditions": [
|
|
{
|
|
"key": "content.msgtype",
|
|
"kind": "event_match",
|
|
"pattern": "m.notice"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.suppress_notices"
|
|
}
|
|
],
|
|
"room": [],
|
|
"sender": [],
|
|
"underride": [
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "sound",
|
|
"value": "ring"
|
|
},
|
|
{
|
|
"set_tweak": "highlight",
|
|
"value": false
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"key": "type",
|
|
"kind": "event_match",
|
|
"pattern": "m.call.invite"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.call"
|
|
},
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "sound",
|
|
"value": "default"
|
|
},
|
|
{
|
|
"set_tweak": "highlight"
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"kind": "contains_display_name"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.contains_display_name"
|
|
},
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "sound",
|
|
"value": "default"
|
|
},
|
|
{
|
|
"set_tweak": "highlight",
|
|
"value": false
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"is": "2",
|
|
"kind": "room_member_count"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.room_one_to_one"
|
|
},
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "sound",
|
|
"value": "default"
|
|
},
|
|
{
|
|
"set_tweak": "highlight",
|
|
"value": false
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"key": "type",
|
|
"kind": "event_match",
|
|
"pattern": "m.room.member"
|
|
},
|
|
{
|
|
"key": "content.membership",
|
|
"kind": "event_match",
|
|
"pattern": "invite"
|
|
},
|
|
{
|
|
"key": "state_key",
|
|
"kind": "event_match",
|
|
"pattern": "@alice:example.com"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.invite_for_me"
|
|
},
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "highlight",
|
|
"value": false
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"key": "type",
|
|
"kind": "event_match",
|
|
"pattern": "m.room.member"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.member_event"
|
|
},
|
|
{
|
|
"actions": [
|
|
"notify",
|
|
{
|
|
"set_tweak": "highlight",
|
|
"value": false
|
|
}
|
|
],
|
|
"conditions": [
|
|
{
|
|
"key": "type",
|
|
"kind": "event_match",
|
|
"pattern": "m.room.message"
|
|
}
|
|
],
|
|
"default": true,
|
|
"enabled": true,
|
|
"rule_id": ".m.rule.message"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
tags:
|
|
- Push notifications
|
|
"/pushrules/{scope}/{kind}/{ruleId}":
|
|
get:
|
|
summary: Retrieve a push rule.
|
|
description: |-
|
|
Retrieve a single specified push rule.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
``global`` to specify global rules.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: content
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: "nocake"
|
|
description: |
|
|
The identifier for the rule.
|
|
responses:
|
|
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.
|
|
examples:
|
|
application/json: {
|
|
"actions": [
|
|
"dont_notify"
|
|
],
|
|
"pattern": "cake*lie",
|
|
"rule_id": "nocake",
|
|
"enabled": true,
|
|
"default": false
|
|
}
|
|
schema:
|
|
type: object
|
|
description: The push rule.
|
|
allOf: [
|
|
"$ref": "definitions/push_rule.yaml"
|
|
]
|
|
tags:
|
|
- Push notifications
|
|
delete:
|
|
summary: Delete a push rule.
|
|
description: |-
|
|
This endpoint removes the push rule defined in the path.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
``global`` to specify global rules.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: content
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: "nocake"
|
|
description: |
|
|
The identifier for the rule.
|
|
responses:
|
|
200:
|
|
description: The push rule was deleted.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object # empty json object
|
|
tags:
|
|
- Push notifications
|
|
put:
|
|
summary: Add or change a push rule.
|
|
description: |-
|
|
This endpoint allows the creation, modification and deletion of pushers
|
|
for this user ID. The behaviour of this endpoint varies depending on the
|
|
values in the JSON body.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
``global`` to specify global rules.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: content
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: "nocake"
|
|
description: |
|
|
The identifier for the rule.
|
|
- in: query
|
|
type: string
|
|
name: before
|
|
required: false
|
|
x-example: someRuleId
|
|
description: |-
|
|
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
|
|
type: string
|
|
name: after
|
|
required: false
|
|
x-example: anotherRuleId
|
|
description: |-
|
|
This makes the new rule the next-less important rule relative to the
|
|
given user defined rule. It is not possible to add a rule relative
|
|
to a predefined server rule.
|
|
- in: body
|
|
name: pushrule
|
|
description: |-
|
|
The push rule data. Additional top-level keys may be present depending
|
|
on the parameters for the rule ``kind``.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"pattern": "cake*lie",
|
|
"actions": ["notify"]
|
|
}
|
|
properties:
|
|
actions:
|
|
type: array
|
|
description: |-
|
|
The action(s) to perform when the conditions for this rule are met.
|
|
items:
|
|
type: string
|
|
enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
|
|
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
|
|
conditions:
|
|
type: array
|
|
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.
|
|
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.
|
|
required: ["actions"]
|
|
responses:
|
|
200:
|
|
description: The pusher was set.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object # empty json object
|
|
400:
|
|
description: There was a problem configuring this push rule.
|
|
examples:
|
|
application/json: {
|
|
"error": "before/after rule not found: someRuleId",
|
|
"errcode": "M_UNKNOWN"
|
|
}
|
|
schema:
|
|
type: object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
tags:
|
|
- Push notifications
|
|
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
|
|
get:
|
|
summary: "Get whether a push rule is enabled"
|
|
description:
|
|
This endpoint gets whether the specified push rule is enabled.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
Either ``global`` or ``device/<profile_tag>`` to specify global
|
|
rules or device rules for the given ``profile_tag``.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: cake
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: nocake
|
|
description: |
|
|
The identifier for the rule.
|
|
responses:
|
|
200:
|
|
description: Whether the push rule is enabled.
|
|
examples:
|
|
application/json: {
|
|
"enabled": true
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether the push rule is enabled or not.
|
|
required: ["enabled"]
|
|
put:
|
|
summary: "Enable or disable a push rule."
|
|
description: |-
|
|
This endpoint allows clients to enable or disable the specified push rule.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
``global`` to specify global rules.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: content
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: "nocake"
|
|
description: |
|
|
The identifier for the rule.
|
|
- in: body
|
|
name: body
|
|
description: |
|
|
Whether the push rule is enabled or not.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether the push rule is enabled or not.
|
|
required: ["enabled"]
|
|
example: {
|
|
"enabled": true
|
|
}
|
|
responses:
|
|
200:
|
|
description: The push rule was enabled or disabled.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object
|
|
tags:
|
|
- Push notifications
|
|
"/pushrules/{scope}/{kind}/{ruleId}/actions":
|
|
get:
|
|
summary: "The actions for a push rule"
|
|
description:
|
|
This endpoint get the actions for the specified push rule.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
Either ``global`` or ``device/<profile_tag>`` to specify global
|
|
rules or device rules for the given ``profile_tag``.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: content
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: nocake
|
|
description: |
|
|
The identifier for the rule.
|
|
responses:
|
|
200:
|
|
description: The actions for this push rule.
|
|
examples:
|
|
application/json: {
|
|
"actions": ["notify"]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
actions:
|
|
type: array
|
|
description: The action(s) to perform for this rule.
|
|
items:
|
|
type: string
|
|
required: ["actions"]
|
|
put:
|
|
summary: "Set the actions for a push rule."
|
|
description: |-
|
|
This endpoint allows clients to change the actions of a push rule.
|
|
This can be used to change the actions of builtin rules.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: scope
|
|
required: true
|
|
x-example: "global"
|
|
description: |-
|
|
``global`` to specify global rules.
|
|
- in: path
|
|
type: string
|
|
name: kind
|
|
required: true
|
|
x-example: room
|
|
enum: ["override", "underride", "sender", "room", "content"]
|
|
description: |
|
|
The kind of rule
|
|
- in: path
|
|
type: string
|
|
name: ruleId
|
|
required: true
|
|
x-example: "#spam:example.com"
|
|
description: |
|
|
The identifier for the rule.
|
|
- in: body
|
|
name: body
|
|
description: |
|
|
The action(s) to perform when the conditions for this rule are met.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
actions:
|
|
type: array
|
|
description: The action(s) to perform for this rule.
|
|
items:
|
|
type: string
|
|
enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
|
|
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
|
|
required: ["actions"]
|
|
example: {
|
|
"actions": ["notify"]
|
|
}
|
|
responses:
|
|
200:
|
|
description: The actions for the push rule were set.
|
|
examples:
|
|
application/json: {
|
|
}
|
|
schema:
|
|
type: object
|
|
tags:
|
|
- Push notifications
|