particle_alert_create

{
  "properties": {
    "delivery_cadence": {
      "description": "How often matches are emailed: REALTIME (default, one email per match), DAILY (one bundled email each morning), or WEEKLY (one bundled email Monday).",
      "enum": [
        "REALTIME",
        "DAILY",
        "WEEKLY"
      ],
      "type": "string"
    },
    "description": {
      "description": "Optional longer description of what the alert is for.",
      "type": "string"
    },
    "entities": {
      "description": "The entity to watch, as a single slug from the resolve tools (particle_entity_resolve, particle_person_resolve, particle_company_resolve). Person, company, and place/other (knowledge-graph) slugs are all accepted; the resolved type is echoed back in the response. Exactly one — an alert watches a single entity, so create one alert per entity.",
      "items": {
        "type": "string"
      },
      "maxItems": 1,
      "minItems": 1,
      "type": "array"
    },
    "filters": {
      "description": "Persistent narrowing applied to every surface the alert produces (matches list, realtime email, daily/weekly digest). Omit for no filters — every detected match is surfaced. See AlertFiltersInput for the four axes (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": "Whether the alert produces matches. Defaults to true. Set false to create it paused.",
      "type": "boolean"
    },
    "kind": {
      "description": "What signal to watch for. ENTITY_MENTION (default) fires whenever a watched entity is mentioned on a podcast episode. PODCAST_SPEAKER fires only when a watched person is themself an identified speaker (guest/panelist/correspondent/audience). Kind is fixed at creation.",
      "enum": [
        "ENTITY_MENTION",
        "PODCAST_SPEAKER"
      ],
      "type": "string"
    },
    "notifications": {
      "description": "Email addresses to notify. Each must already be verified for your organization (or belong to an org member). When omitted, defaults to your account email if available; otherwise pass at least one.",
      "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": "Human-readable title for the alert (e.g. 'OpenAI mentions').",
      "type": "string"
    }
  },
  "required": [
    "title",
    "entities"
  ],
  "type": "object"
}