particle_alert_update

{
  "properties": {
    "alert_id": {
      "description": "Alert id to update.",
      "type": "string"
    },
    "delivery_cadence": {
      "description": "New delivery cadence.",
      "enum": [
        "REALTIME",
        "DAILY",
        "WEEKLY"
      ],
      "type": "string"
    },
    "description": {
      "description": "New description.",
      "type": "string"
    },
    "entities": {
      "description": "Replacement watch target as a single entity slug (from the resolve tools). When provided, replaces the entire existing watch list — exactly one entity; omit to leave entities unchanged.",
      "items": {
        "type": "string"
      },
      "maxItems": 1,
      "minItems": 1,
      "type": "array"
    },
    "filters": {
      "description": "Replace the alert's filter set wholesale. Omit to leave the existing filters unchanged; send an empty object {} to clear all filters. Same four axes as particle_alert_create.filters (languages, relevance, source_popularity, speaker_roles).",
      "properties": {
        "languages": {
          "description": "Primary language tags the source episode must be in: a 2-3 letter primary tag (e.g. 'en', 'de', 'sma'). A region or script subtag (e.g. 'pt-BR', 'zh-Hant') is accepted for readability but matching is on the PRIMARY tag only — 'pt-BR' surfaces every Portuguese episode regardless of region, and 'pt-BR' + 'pt-PT' collapse to one. Empty or missing means all languages are surfaced. Case-insensitive; echoed in canonical primary-tag form.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "relevance": {
          "description": "EVERYTHING (default) returns both on-target and incidental matches — the watched entity is correctly identified in both, only the depth of discussion differs. RELEVANT narrows to on-target only: matches where the watched entity is the subject being discussed, dropping passing mentions. Wrong-entity matches (name collisions) are globally suppressed before any filter runs.",
          "enum": [
            "EVERYTHING",
            "RELEVANT"
          ],
          "type": "string"
        },
        "source_popularity": {
          "description": "ANY (default) keeps matches from every source. POPULAR keeps only matches whose source podcast scores in the top 5% by chart-popularity percentile (Podcast.Popularity >= 0.95; cume_dist over current chart entries, multi-region weighted). Podcasts that aren't currently charting drop out.",
          "enum": [
            "ANY",
            "POPULAR"
          ],
          "type": "string"
        },
        "speaker_roles": {
          "description": "PODCAST_SPEAKER alerts only — sending this on an ENTITY_MENTION alert returns an unprocessable_entity error. REPLACES (not intersects with) the default appearance set. Default when omitted is GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER — HOST is excluded because hosting the show isn't an appearance. Setting ['HOST'] flips that; setting ['GUEST'] alone narrows further. Input casing is not significant — 'guest' and 'GUEST' are the same value — and the filter is stored and returned in canonical uppercase form. Raw STT/LLM labels like CALLER or REPORTER are not accepted.",
          "items": {
            "enum": [
              "HOST",
              "GUEST",
              "PANELIST",
              "CORRESPONDENT",
              "AUDIENCE",
              "SOUNDBITE_SPEAKER"
            ],
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "is_active": {
      "description": "Pause (false) or resume (true) the alert.",
      "type": "boolean"
    },
    "notifications": {
      "description": "Replacement notification emails. When provided, replaces the entire existing set; omit to leave them unchanged.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "output_format": {
      "description": "Output serialization. 'markdown' (default) returns the LLM-facing rendering. 'json' returns the structured payload as JSON text — use only for programmatic chaining where exact field extraction matters; the JSON shape is larger and noisier for an LLM to read.",
      "enum": [
        "markdown",
        "json"
      ],
      "type": "string"
    },
    "title": {
      "description": "New title.",
      "type": "string"
    }
  },
  "required": [
    "alert_id"
  ],
  "type": "object"
}