matrix-spec/data/api/client-server/pushrules.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.
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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
                    type: ["string", "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:
                    $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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: scope
          required: true
          description: |-
            Either `global` or `device/<profile_tag>` 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: 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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: scope
          required: true
          description: |-
            Either `global` or `device/<profile_tag>` 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:
                      type: ["string", "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:
        - accessTokenQuery: []
        - accessTokenBearer: []
      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:
                    type: ["string", "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:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer