Update an alert

Partially update an alert. Provided fields replace existing values; the entities list, when provided, replaces the watched entity (exactly one).

PATCH /v1/alerts/{id}

cURL

cURL

curl -X PATCH \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.particle.pro/v1/alerts/{id}"

200

{
  "created_at": "2023-11-07T05:31:56Z",
  "delivery_cadence": "<string>",
  "entities": [
    {
      "entity_id": "<string>",
      "entity_type": "PERSON",
      "image_url": "<string>",
      "name": "<string>"
    }
  ],
  "id": "<string>",
  "is_active": true,
  "kind": "ENTITY_MENTION",
  "notifications": [
    {
      "type": "EMAIL",
      "created_by": {
        "id": "<string>",
        "name": "<string>"
      },
      "email": "[e-mail]",
      "id": "<string>",
      "slack_channel_id": "<string>",
      "slack_channel_name": "<string>",
      "slack_connection_id": "<string>",
      "webhook_connection_id": "<string>"
    }
  ],
  "project_id": "<string>",
  "title": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": {
    "id": "<string>",
    "name": "<string>"
  },
  "description": "<string>",
  "filters": {
    "languages": [
      "<string>"
    ],
    "relevance": "EVERYTHING",
    "source_popularity": "ANY",
    "speaker_roles": [
      "HOST"
    ]
  }
}

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Path Parameters

id · string · required

Alert ID

Body

application/json

delivery_cadence · enum<string>

Available options: REALTIME, DAILY, WEEKLY

description · string

Maximum string length: 2000

entities · object[]

Replacement watch target — exactly one entity. Alerts created before the one-entity rule keep their multi-entity watch list until this field is next written.

Required array length: 1 element

Show child attributes

filters · object

Replace the alert's filter set wholesale. Omit to leave the existing filters unchanged; send an empty object {} to clear all filters.

Show child attributes

is_active · boolean

Toggle whether the alert produces matches. False pauses; true resumes.

notifications · object[]

Required array length: 1 - 20 elements

Show child attributes

title · string

Required string length: 1 - 200

Response

200

application/json

OK

created_at · string<date-time> · required

delivery_cadence · string · required

How often matches are delivered: REALTIME (a separate email per match), DAILY (one bundled email each morning at 13:00 UTC), or WEEKLY (one bundled email Monday 13:00 UTC). Defaults to REALTIME.

entities · object[] | null · required

Show child attributes

id · string · required

is_active · boolean · required

Whether the alert produces matches. Disabled alerts retain history but accumulate no new matches until re-enabled.

kind · enum<string> · required

What signal the alert watches for. ENTITY_MENTION fires whenever a watched entity is mentioned in a podcast episode. PODCAST_SPEAKER fires only when a watched entity is themself an identified speaker on the episode, in one of the canonical appearance buckets — GUEST, PANELIST, CORRESPONDENT, or AUDIENCE (this last bucket absorbs callers, listeners, and other audience-side roles after server-side canonicalization). HOST is intentionally excluded — hosting the show isn't an appearance. Kind is fixed at creation.

Available options: ENTITY_MENTION, PODCAST_SPEAKER

notifications · object[] | null · required

Show child attributes

project_id · string · required

title · string · required

updated_at · string<date-time> · required

created_by · object

User who created the alert. Null when the alert was created via an API key.

Show child attributes

description · string

filters · object

Persistent narrowing applied to every surface the alert produces: the matches list, the realtime email, and the daily/weekly digest. Absent = no filters (every detected match is surfaced).

Show child attributes