---
title: "Update an alert rule"
method: PATCH
path: "/alert-rules/{rule_id}"
tags: ["alerts"]
---

# Update an alert rule

`PATCH /alert-rules/{rule_id}`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/alert-rules/{rule_id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:write`)

## Path parameters

- `rule_id` string, required

## Query parameters

- `project` string

## Headers

- `Bisibility-API-Version` 'v1'
- `Idempotency-Key` string
- `X-Bisibility-Project` string
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Request body

- AlertRulePatch: name and condition_type are required for create and PATCH. Condition-specific fields must be supplied: threshold_position for threshold, change_pct for change_pct/ctr_drop (at most 100 for ctr_drop), drop_positions for position_drop, top_n for enters_top_n/exits_top_n, competitor_domain for competitor_overtake, serp_feature for serp_feature. Non-all targets require target_ids. Nullable condition fields accept null independently of omission. Omitted market_ids and recipient_ids preserve scope and recipients; empty arrays clear them. Other defaulted fields retain the form defaults (enabled true, channels/target_ids empty, target_type all).
  - `channels` string[]: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
  - `change_pct` number, nullable
  - `competitor_domain` string, nullable
  - `condition_type` 'threshold' | 'change_pct' | 'ctr_drop' | 'position_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'competitor_overtake' | 'serp_feature' | 'url_mismatch', required
  - `drop_positions` integer, nullable
  - `enabled` boolean
  - `name` string, required
  - `market_ids` string[]
  - `recipient_ids` string[]
  - `serp_feature` string, nullable
  - `severity` 'info' | 'warning' | 'urgent'
  - `target_ids` union[]
    - union
      - string
      - string
  - `target_type` 'all' | 'keyword' | 'tag'
  - `threshold_position` integer, nullable
  - `top_n` integer, nullable

## Response `200`

JSON response

- union: An alert rule. target_ids follow target_type: keyword IDs, tag IDs, or empty for all keywords.
  - object
    - `channels` string[], required: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
    - `change_pct` number, nullable, required
    - `competitor_domain` string, nullable, required
    - `condition_type` 'threshold' | 'change_pct' | 'ctr_drop' | 'position_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'competitor_overtake' | 'serp_feature' | 'url_mismatch', required
    - `drop_positions` integer, nullable, required
    - `enabled` boolean, required
    - `name` string, required
    - `market_ids` string[], required
    - `recipient_ids` string[], required
    - `serp_feature` string, nullable, required
    - `severity` 'info' | 'warning' | 'urgent', required
    - `target_ids` string[], required
    - `target_type` 'keyword', required
    - `threshold_position` integer, nullable, required
    - `top_n` integer, nullable, required
    - `channel` string, required: Display label for the delivery channels.
    - `condition` string, required: Display sentence for the rule condition.
    - `fires` string, required: Display count of triggers in the last seven days.
    - `id` string, required
    - `market_scope` string: Display label for the market scope.
    - `period` string, required: Display label for the evaluation period.
    - `scope` string, required: Display label for the targeted keywords or tags.
    - `status` 'active' | 'learning' | 'paused' | 'setup', required
  - object
    - `channels` string[], required: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
    - `change_pct` number, nullable, required
    - `competitor_domain` string, nullable, required
    - `condition_type` 'threshold' | 'change_pct' | 'ctr_drop' | 'position_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'competitor_overtake' | 'serp_feature' | 'url_mismatch', required
    - `drop_positions` integer, nullable, required
    - `enabled` boolean, required
    - `name` string, required
    - `market_ids` string[], required
    - `recipient_ids` string[], required
    - `serp_feature` string, nullable, required
    - `severity` 'info' | 'warning' | 'urgent', required
    - `target_ids` string[], required
    - `target_type` 'tag', required
    - `threshold_position` integer, nullable, required
    - `top_n` integer, nullable, required
    - `channel` string, required: Display label for the delivery channels.
    - `condition` string, required: Display sentence for the rule condition.
    - `fires` string, required: Display count of triggers in the last seven days.
    - `id` string, required
    - `market_scope` string: Display label for the market scope.
    - `period` string, required: Display label for the evaluation period.
    - `scope` string, required: Display label for the targeted keywords or tags.
    - `status` 'active' | 'learning' | 'paused' | 'setup', required
  - object
    - `channels` string[], required: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
    - `change_pct` number, nullable, required
    - `competitor_domain` string, nullable, required
    - `condition_type` 'threshold' | 'change_pct' | 'ctr_drop' | 'position_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'competitor_overtake' | 'serp_feature' | 'url_mismatch', required
    - `drop_positions` integer, nullable, required
    - `enabled` boolean, required
    - `name` string, required
    - `market_ids` string[], required
    - `recipient_ids` string[], required
    - `serp_feature` string, nullable, required
    - `severity` 'info' | 'warning' | 'urgent', required
    - `target_ids` string[], required
    - `target_type` 'all', required
    - `threshold_position` integer, nullable, required
    - `top_n` integer, nullable, required
    - `channel` string, required: Display label for the delivery channels.
    - `condition` string, required: Display sentence for the rule condition.
    - `fires` string, required: Display count of triggers in the last seven days.
    - `id` string, required
    - `market_scope` string: Display label for the market scope.
    - `period` string, required: Display label for the evaluation period.
    - `scope` string, required: Display label for the targeted keywords or tags.
    - `status` 'active' | 'learning' | 'paused' | 'setup', required
  - object
    - `channels` string[], required: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
    - `change_pct` number, nullable, required
    - `competitor_domain` string, nullable, required
    - `condition_type` 'threshold' | 'change_pct' | 'ctr_drop' | 'position_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'competitor_overtake' | 'serp_feature' | 'url_mismatch', required
    - `drop_positions` integer, nullable, required
    - `enabled` boolean, required
    - `name` string, required
    - `market_ids` string[], required
    - `recipient_ids` string[], required
    - `serp_feature` string, nullable, required
    - `severity` 'info' | 'warning' | 'urgent', required
    - `target_ids` union[], required
      - union
        - string
        - string
    - `target_type` 'all' | 'keyword' | 'tag', required
    - `threshold_position` integer, nullable, required
    - `top_n` integer, nullable, required
    - `channel` string, required: Display label for the delivery channels.
    - `condition` string, required: Display sentence for the rule condition.
    - `fires` string, required: Display count of triggers in the last seven days.
    - `id` string, required
    - `market_scope` string: Display label for the market scope.
    - `period` string, required: Display label for the evaluation period.
    - `scope` string, required: Display label for the targeted keywords or tags.
    - `status` 'active' | 'learning' | 'paused' | 'setup', required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Unsupported API version
- `429`: Rate limited

## Changes

- **2026-10-19** `a6e1ec0dec82`: 9 breaking, 15 warning, 14 info
  - added the new path request parameter `rule_id`
  - request body became required
  - the `market_ids/items/` request property's minLength was increased from `0` to `1`
  - the `recipient_ids/items/` request property's minLength was increased from `0` to `1`
  - …34 more

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/alert-rules/:rule_id/patch.md)

---

[API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)