> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Competitor Alerts

> Choose where competitor alerts go, and when an account alerts

Turn competitor alerts on or off, and for Attack and for Defense pick the Slack channel and
whether each alert is emailed. Set up the webhook, the Attack threshold and its scope, and how
far back a single interaction still alerts.

Each alert type has its own rule: the interactions that count (`*_interaction_kinds`), the
minimum people engaged at the account (`*_min_people`), the period (`*_period_days`), and whether
a single comment in the period is enough on its own (`*_comment_alone`). An account alerts once
per monitoring run, listing every person engaged, when it meets the rule and someone new was
engaged.

Each alert is posted in its use case's channel, naming the owner from your
CRM (the account owner for Attack, the CS owner for Defense, read live when the alert is sent,
nobody when the field is empty), emailed to that owner and the use case's extra addresses when
email is on, and POSTed to the webhook when it is on.

Send only the fields you want to change; a field you leave out keeps its saved value. Admin
only.

> [!WARNING]
>
> **No channel, no email and no webhook means no alerts.** Saving with none is allowed, and the
> response says so with `has_delivery: false`. With email on but no owner in your CRM and no
> extra address, that alert is not emailed.

```bash cURL theme={null}
curl -X PUT https://api.clustr-ai.com/api/public/notifications/competitor-alerts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attack_slack_channel_id": "C0123456789", "defense_slack_channel_id": "C0987654321", "attack_email_enabled": true, "attack_email_recipients": ["sales-leads@example.com"], "attack_threshold_interactions": 5, "attack_threshold_days": 30, "attack_threshold_scope": "all_competitors", "alert_history_days": 21}'
```

```python Python theme={null}
import requests

requests.put(
    "https://api.clustr-ai.com/api/public/notifications/competitor-alerts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "attack_slack_channel_id": "C0123456789",
        "defense_slack_channel_id": "C0987654321",
        "attack_email_enabled": True,
        "attack_email_recipients": ["sales-leads@example.com"],
        "attack_threshold_interactions": 5,
        "attack_threshold_days": 30,
        "attack_threshold_scope": "all_competitors",
        "alert_history_days": 21,
    },
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/notifications/competitor-alerts", {
  method: "PUT",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    attack_slack_channel_id: "C0123456789",
    defense_slack_channel_id: "C0987654321",
    attack_email_enabled: true,
    attack_email_recipients: ["sales-leads@example.com"],
    attack_threshold_interactions: 5,
    attack_threshold_days: 30,
    attack_threshold_scope: "all_competitors",
    alert_history_days: 21,
  }),
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "enabled": true,
    "attack_slack_channel_id": "C0123456789",
    "defense_slack_channel_id": "C0987654321",
    "attack_email_enabled": true,
    "defense_email_enabled": false,
    "attack_email_recipients": ["sales-leads@example.com"],
    "defense_email_recipients": [],
    "webhook_enabled": false,
    "webhook_url": null,
    "has_webhook_secret": false,
    "attack_threshold_interactions": 5,
    "attack_threshold_days": 30,
    "attack_threshold_scope": "all_competitors",
    "alert_history_days": 21,
    "has_delivery": true,
    "customers": true,
    "targets": true,
    "notify_defaults": true,
    "slack_dm": true,
    "slack_channel_id": null,
    "recipients": [],
    "is_default": false,
    "updated_at": "2026-10-08T09:12:44Z",
    "admins": []
  }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": {
    "message": "attack_threshold_scope must be per_competitor or all_competitors",
    "code": "BAD_REQUEST"
  }
}
```


## OpenAPI

````yaml PUT /notifications/competitor-alerts
openapi: 3.1.0
info:
  title: Clustr Public API
  description: >
    Programmatic access to your Clustr network: import connectors, search warm
    intros (opportunities), and manage target accounts.


    ## Authentication

    All endpoints require a Bearer token (API key) in the `Authorization`
    header.


    ```

    Authorization: Bearer <your_api_key>

    ```


    API keys can be created and managed from the [API settings
    page](https://app.clustr-ai.com/api).
  version: '1.0'
  contact:
    name: Clustr Support
    url: https://clustr-ai.com
servers:
  - url: https://api.clustr-ai.com/api/public
    description: Production
security:
  - BearerAuth: []
paths:
  /notifications/competitor-alerts:
    put:
      tags:
        - Competitor Monitoring
      summary: Update Competitor Alerts
      description: >
        Turn competitor alerts on or off, pick the Attack and Defense Slack
        channels and

        emails, the webhook, the Attack threshold and its scope, and the history
        window.

        Every field is optional; a field you leave out keeps its saved value.
        Admin only.
      operationId: updateCompetitorAlerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompetitorAlertsUpdateRequest'
            examples:
              channels:
                summary: Post Attack and Defense alerts, and email Attack alerts
                value:
                  attack_slack_channel_id: C0123456789
                  defense_slack_channel_id: C0987654321
                  attack_email_enabled: true
      responses:
        '200':
          description: The saved setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorAlertsResponse'
        '400':
          description: >-
            An invalid channel id, email address, webhook URL, threshold, scope
            or history window
        '401':
          description: Invalid or missing API key
        '403':
          description: The caller is not a workspace admin
components:
  schemas:
    CompetitorAlertsUpdateRequest:
      type: object
      properties:
        enabled:
          type: boolean
          description: >-
            Whether competitor alerts go out. `false` stops every Slack post,
            email, webhook call and team refresh recap.
        attack_slack_channel_id:
          type: string
          description: >-
            The Slack channel Attack alerts post in, as a Slack channel id such
            as `C0123456789`. An empty string clears it.
        defense_slack_channel_id:
          type: string
          description: >-
            The Slack channel Defense alerts post in. May be the same as the
            Attack channel. An empty

            string clears it.
        attack_email_enabled:
          type: boolean
          description: >-
            Email each Attack alert to the account owner from your CRM and to
            `attack_email_recipients`.
        defense_email_enabled:
          type: boolean
          description: >-
            Email each Defense alert to the CS owner from your CRM and to
            `defense_email_recipients`.
        attack_email_recipients:
          type: array
          description: >-
            Extra addresses that get every Attack alert by email, at most 50.
            Replaces the saved list; an

            empty list clears it. An address without an `@` is a `400`.
          maxItems: 50
          items:
            type: string
            format: email
        defense_email_recipients:
          type: array
          description: >-
            Extra addresses that get every Defense alert by email, at most 50.
            Replaces the saved list.
          maxItems: 50
          items:
            type: string
            format: email
        webhook_enabled:
          type: boolean
          description: >-
            Sends every alert and every team refresh recap to `webhook_url` as a
            POST request. Requires `webhook_url`; without one the call answers
            `400`.
        webhook_url:
          type: string
          description: >-
            The endpoint, `https://` (or `http://`) with a host, at most 2048
            characters. An empty string

            clears it. See [Webhook
            payloads](/competitor-monitoring/webhook-payload).
        webhook_secret:
          type: string
          writeOnly: true
          description: >-
            The secret that signs each request with `X-ClustR-Signature`. It is
            write-only: the response reports `has_webhook_secret` in its place.
            Leave it out to keep the saved secret; an empty string removes it.
            At most 256 characters.
        attack_threshold_interactions:
          type: integer
          description: >-
            An account that is not a customer alerts when it has at least this
            many interactions over

            `attack_threshold_days`. From 1 to 10000. Default 10.
          minimum: 1
          maximum: 10000
        attack_threshold_days:
          type: integer
          description: >-
            The period the threshold counts over, in days. From 1 to 365.
            Default 30.
          minimum: 1
          maximum: 365
        attack_threshold_scope:
          type: string
          description: >-
            `per_competitor` (default) counts an account's interactions with
            each competitor's team on

            its own. `all_competitors` counts them across all your competitors
            together; the alert then

            names the most active one.
          enum:
            - per_competitor
            - all_competitors
        alert_history_days:
          type: integer
          description: >-
            How old a Defense interaction or a critical comment may be and still
            alert, in days. From 1 to 365. Default 14. Older activity still
            appears in every view without alerting.
          minimum: 1
          maximum: 365
        customers:
          type: boolean
          description: 'Defense alerts: interactions on one of your customers.'
        targets:
          type: boolean
          description: >-
            Attack alerts: critical comments and threshold alerts on accounts
            that are not customers,

            both your target accounts and every other account a competitor
            engages with. Each alert is

            labelled "Target account" or "Other account" (`account_scope` in the
            webhook).
        attack_other_accounts:
          type: boolean
          description: >-
            `true` (default) keeps the Attack alerts on other accounts, the
            non-customers that are not on

            your target account list. `false` mutes them: Attack then alerts on
            your target accounts only.
        defense_interaction_kinds:
          type: array
          items:
            type: string
            enum:
              - comment
              - like
          description: >-
            Defense alerts: the interactions that count, `comment` and/or
            `like`. Default both.
        attack_interaction_kinds:
          type: array
          items:
            type: string
            enum:
              - comment
              - like
          description: >-
            Attack alerts: the interactions that count, `comment` and/or `like`.
            Default both.
        defense_min_people:
          type: integer
          description: >-
            Defense alerts: an account alerts once this many people there were
            engaged in the period. Default 2.
        attack_min_people:
          type: integer
          description: >-
            Attack alerts: an account alerts once this many people there were
            engaged in the period. Default 2.
        defense_period_days:
          type: integer
          description: >-
            Defense alerts: the period the people engaged are counted over, in
            days (1 to 365). Default 30.
        attack_period_days:
          type: integer
          description: >-
            Attack alerts: the period the people engaged are counted over, in
            days (1 to 365). Default 30.
        defense_comment_alone:
          type: boolean
          description: >-
            Defense alerts: a comment is enough. An account also alerts when one
            comment there falls in the period, below `defense_min_people`.
        attack_comment_alone:
          type: boolean
          description: >-
            Attack alerts: a comment is enough. An account also alerts when one
            comment there falls in the period, below `attack_min_people`.
        notify_defaults:
          type: boolean
        slack_dm:
          type: boolean
        slack_channel_id:
          type: string
        recipients:
          type: array
          items:
            type: string
            format: email
    CompetitorAlertsResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            enabled:
              type: boolean
              description: >-
                Whether competitor alerts are sent. On by default; `false` stops
                alerts on every channel.
            attack_slack_channel_id:
              type: string
              nullable: true
              description: Slack channel Attack alerts post in.
            defense_slack_channel_id:
              type: string
              nullable: true
              description: >-
                Slack channel Defense alerts post in. May equal the Attack
                channel.
            attack_email_enabled:
              type: boolean
              description: >-
                Email each Attack alert to the account owner and
                attack_email_recipients.
            defense_email_enabled:
              type: boolean
              description: >-
                Email each Defense alert to the CS owner and
                defense_email_recipients.
            attack_email_recipients:
              type: array
              items:
                type: string
                format: email
            defense_email_recipients:
              type: array
              items:
                type: string
                format: email
            webhook_enabled:
              type: boolean
            webhook_url:
              type: string
              nullable: true
            has_webhook_secret:
              type: boolean
              description: >-
                True when a webhook signing secret is saved. The secret itself
                is write-only.
            attack_threshold_interactions:
              type: integer
              description: >-
                The Attack threshold: an account with at least this many
                interactions within `attack_threshold_days` triggers an Attack
                alert. Between 1 and 10,000; default 10.
            attack_threshold_days:
              type: integer
              description: >-
                The window, in days, over which `attack_threshold_interactions`
                is counted. Between 1 and 365; default 30.
            attack_threshold_scope:
              type: string
              enum:
                - per_competitor
                - all_competitors
            alert_history_days:
              type: integer
              description: >-
                How old an interaction may be and still alert on its own.
                Default 14.
            has_delivery:
              type: boolean
              description: >-
                True when at least one Slack channel, email or webhook is set up
                to receive alerts. Alerts are sent only when it is true.
            customers:
              type: boolean
            targets:
              type: boolean
              description: >-
                Whether Attack alerts are sent. They cover target accounts and
                every other account that is not a customer, each labelled with
                its kind.
            attack_other_accounts:
              type: boolean
              description: >-
                True (the default) also alerts on other accounts, the
                non-customers that are not on your target account list, labelled
                Other account. False mutes them.
            defense_interaction_kinds:
              type: array
              items:
                type: string
                enum:
                  - comment
                  - like
              description: >-
                Defense alerts: the interactions that count, `comment` and/or
                `like`. Default both.
            attack_interaction_kinds:
              type: array
              items:
                type: string
                enum:
                  - comment
                  - like
              description: >-
                Attack alerts: the interactions that count, `comment` and/or
                `like`. Default both.
            defense_min_people:
              type: integer
              description: >-
                Defense alerts: an account alerts once this many people there
                were engaged in the period. Default 2.
            attack_min_people:
              type: integer
              description: >-
                Attack alerts: an account alerts once this many people there
                were engaged in the period. Default 2.
            defense_period_days:
              type: integer
              description: >-
                Defense alerts: the period the people engaged are counted over,
                in days (1 to 365). Default 30.
            attack_period_days:
              type: integer
              description: >-
                Attack alerts: the period the people engaged are counted over,
                in days (1 to 365). Default 30.
            defense_comment_alone:
              type: boolean
              description: >-
                Defense alerts: a comment is enough. An account also alerts when
                one comment there falls in the period, below
                `defense_min_people`. Default true.
            attack_comment_alone:
              type: boolean
              description: >-
                Attack alerts: a comment is enough. An account also alerts when
                one comment there falls in the period, below
                `attack_min_people`. Default true.
            notify_defaults:
              type: boolean
              description: >-
                Stored and returned as sent. Alert delivery uses the Attack and
                Defense settings above.
            slack_dm:
              type: boolean
              description: >-
                Stored and returned as sent. Alert delivery uses the Attack and
                Defense settings above.
            slack_channel_id:
              type: string
              nullable: true
              description: >-
                Stored and returned as sent. Alert delivery uses the Attack and
                Defense settings above.
            recipients:
              type: array
              description: >-
                Stored and returned as sent. Alert delivery uses the Attack and
                Defense settings above.
              items:
                type: string
                format: email
            is_default:
              type: boolean
              description: True when the workspace never saved the setting.
            updated_at:
              type: string
              format: date-time
            admins:
              type: array
              description: The workspace's admins.
              items:
                type: object
                properties:
                  clustr_user_id:
                    type: string
                    description: >-
                      The member's Clustr ID, for example
                      `usr_tavgqb2hrgsnw3wc0f9sbbjwx0`.
                    example: usr_tavgqb2hrgsnw3wc0f9sbbjwx0
                  user_id:
                    type: string
                    description: >-
                      Kept for integrations built before Clustr IDs. New
                      integrations should use `clustr_user_id`.
                  email:
                    type: string
                    format: email
                  name:
                    type: string
            customer_rule:
              type: object
              description: Who counts as a customer, in one line.
              properties:
                summary:
                  type: string
                count:
                  type: integer
            account:
              type: object
              description: >-
                Present when the request sets `account`: the owner an Attack
                alert on that account names.
              properties:
                name:
                  type: string
                owner:
                  type: object
                  nullable: true
                  description: Null when the CRM names no owner.
                  properties:
                    clustr_user_id:
                      type: string
                      description: >-
                        The member's Clustr ID, for example
                        `usr_tavgqb2hrgsnw3wc0f9sbbjwx0`.
                      example: usr_tavgqb2hrgsnw3wc0f9sbbjwx0
                    user_id:
                      type: string
                      description: >-
                        Kept for integrations built before Clustr IDs. New
                        integrations should use `clustr_user_id`.
                    email:
                      type: string
                      format: email
                    name:
                      type: string
                owner_source:
                  type: string
                  enum:
                    - account_owner
                    - crm_owner
                    - deal_owner
                    - admins
                    - none
                recipients:
                  type: array
                  description: >-
                    Who an Attack alert on it is emailed to, when Attack email
                    is on.
                  items:
                    type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The API key you created on the API settings page of the Clustr app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.