---
title: "Add or change a push rule."
method: PUT
path: "/_matrix/client/v3/pushrules/global/{kind}/{ruleId}"
tags: ["Push notifications"]
---

# Add or change a push rule.

`PUT /_matrix/client/v3/pushrules/global/{kind}/{ruleId}`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/pushrules/global/{kind}/{ruleId}`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/pushrules/global/:kind/:ruleId/put.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `kind` 'override' | 'underride' | 'sender' | 'room' | 'content', required
- `ruleId` string, required

## Query parameters

- `before` string
- `after` string

## Request body

- object
  - `actions` union[], required: The action(s) to perform when the conditions for this rule are met.
    - union
      - string
      - object
  - `conditions` object[]: 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.
    - `is` string: 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 ==.
    - `key` string: Required for `event_match`, `event_property_is` and `event_property_contains` conditions. The dot-separated field of the event to match. 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`.
    - `kind` string, required: The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for more information on the allowed kinds and how they work.
    - `pattern` string: Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.
    - `value` union: Required for `event_property_is` and `event_property_contains` conditions. A non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match against.
      - string
      - integer
      - boolean
  - `pattern` string: Only applicable to `content` rules. The glob-style pattern to match against.

## Response `200`

The push rule was created/updated.

- object

## Other responses

- `400`: There was a problem configuring this push rule.
- `404`: The push rule does not exist (when updating a push rule).
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)