# 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. openapi: 3.1.0 info: title: Matrix Client-Server Push Rules API version: 1.0.0 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. operationId: getPushRules security: - accessToken: [] responses: "200": description: All the push rulesets for this user. content: application/json: schema: type: object required: - global properties: global: type: object description: The global ruleset. title: Ruleset allOf: - $ref: definitions/push_ruleset.yaml examples: response: value: { "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": [], "conditions": [], "default": true, "enabled": false, "rule_id": ".m.rule.master" }, { "actions": [], "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": [ { "kind": "room_member_count", "is": "2" }, { "kind": "event_match", "key": "type", "pattern": "m.room.message" } ], "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. operationId: getPushRule security: - accessToken: [] parameters: - in: path name: scope required: true description: "`global` to specify global rules." example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: content schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: nocake schema: type: string 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. content: application/json: schema: type: object description: The push rule. allOf: - $ref: definitions/push_rule.yaml examples: response: value: { "actions": [], "pattern": "cake*lie", "rule_id": "nocake", "enabled": true, "default": false } "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } tags: - Push notifications delete: summary: Delete a push rule. description: This endpoint removes the push rule defined in the path. operationId: deletePushRule security: - accessToken: [] parameters: - in: path name: scope required: true description: "`global` to specify global rules." example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: content schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: nocake schema: type: string responses: "200": description: The push rule was deleted. content: application/json: schema: type: object # empty json object examples: response: value: {} "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } tags: - Push notifications put: summary: Add or change a push rule. description: |- This endpoint allows the creation and modification of user defined push rules. If a rule with the same `rule_id` already exists among rules of the same kind, it is updated with the new parameters, otherwise a new rule is created. If both `after` and `before` are provided, the new or updated rule must be the next most important rule with respect to the rule identified by `before`. If neither `after` nor `before` are provided and the rule is created, it should be added as the most important user defined rule among rules of the same kind. When creating push rules, they MUST be enabled by default. operationId: setPushRule security: - accessToken: [] parameters: - in: path name: scope required: true description: "`global` to specify global rules." example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: content schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. If the string starts with a dot ("."), the request MUST be rejected as this is reserved for server-default rules. Slashes ("/") and backslashes ("\\") are also not allowed. example: nocake schema: type: string - in: query name: before required: false 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. example: someRuleId schema: type: string - in: query name: after required: false 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. example: anotherRuleId schema: type: string requestBody: content: application/json: 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: oneOf: - type: string - type: object 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 description: |- The push rule data. Additional top-level keys may be present depending on the parameters for the rule `kind`. required: true responses: "200": description: The push rule was created/updated. content: application/json: schema: type: object # empty json object examples: response: value: {} "400": description: There was a problem configuring this push rule. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "error": "before/after rule not found: someRuleId", "errcode": "M_UNKNOWN" } "404": description: The push rule does not exist (when updating a push rule). content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } "429": description: This request was rate-limited. content: application/json: schema: $ref: definitions/errors/rate_limited.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. operationId: isPushRuleEnabled security: - accessToken: [] parameters: - in: path name: scope required: true description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: cake schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: nocake schema: type: string responses: "200": description: Whether the push rule is enabled. content: application/json: schema: type: object properties: enabled: type: boolean description: Whether the push rule is enabled or not. required: - enabled examples: response: value: { "enabled": true } "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } tags: - Push notifications put: summary: Enable or disable a push rule. description: This endpoint allows clients to enable or disable the specified push rule. operationId: setPushRuleEnabled security: - accessToken: [] parameters: - in: path name: scope required: true description: "`global` to specify global rules." example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: content schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: nocake schema: type: string requestBody: content: application/json: schema: type: object properties: enabled: type: boolean description: Whether the push rule is enabled or not. required: - enabled example: { "enabled": true } description: | Whether the push rule is enabled or not. required: true responses: "200": description: The push rule was enabled or disabled. content: application/json: schema: type: object examples: response: value: {} "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } 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. operationId: getPushRuleActions security: - accessToken: [] parameters: - in: path name: scope required: true description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: content schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: nocake schema: type: string responses: "200": description: The actions for this push rule. content: application/json: schema: type: object properties: actions: type: array description: The action(s) to perform for this rule. items: oneOf: - type: string - type: object required: - actions examples: response: value: { "actions": [ "notify", { "set_tweak": "sound", "value": "bing" } ] } "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } tags: - Push notifications 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. operationId: setPushRuleActions security: - accessToken: [] parameters: - in: path name: scope required: true description: "`global` to specify global rules." example: global schema: type: string - in: path name: kind required: true description: | The kind of rule example: room schema: type: string enum: - override - underride - sender - room - content - in: path name: ruleId required: true description: | The identifier for the rule. example: "#spam:example.com" schema: type: string requestBody: content: application/json: schema: type: object properties: actions: type: array description: The action(s) to perform for this rule. items: oneOf: - type: string - type: object required: - actions example: { "actions": [ "notify", { "set_tweak": "highlight" } ] } description: | The action(s) to perform when the conditions for this rule are met. required: true responses: "200": description: The actions for the push rule were set. content: application/json: schema: type: object examples: response: value: {} "404": description: The push rule does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "The push rule was not found." } tags: - Push notifications servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8008 basePath: default: /_matrix/client/v3 components: securitySchemes: $ref: definitions/security.yaml