> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Update an alert > Partially update an alert. Provided fields replace existing values; entity lists, when provided, replace the full set. ## OpenAPI ````yaml /openapi.json patch /v1/alerts/{id} openapi: 3.1.0 info: description: Public API for Particle — news intelligence, financial data, and analysis. title: Particle API version: 0.1.0 servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] paths: /v1/alerts/{id}: patch: tags: - Alerts - tier:standard summary: Update an alert description: >- Partially update an alert. Provided fields replace existing values; entity lists, when provided, replace the full set. operationId: update-alert parameters: - description: Alert ID in: path name: id required: true schema: description: Alert ID type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAlertBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Alert' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -X PATCH \ -H "X-API-Key: $PARTICLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.particle.pro/v1/alerts/{id}" components: schemas: UpdateAlertBody: additionalProperties: false properties: delivery_cadence: enum: - REALTIME - DAILY - WEEKLY type: string description: maxLength: 2000 type: string entities: items: $ref: '#/components/schemas/AlertEntity' maxItems: 100 minItems: 1 type: array filters: $ref: '#/components/schemas/AlertFilters' description: >- Replace the alert's filter set wholesale. Omit to leave the existing filters unchanged; send an empty object {} to clear all filters. is_active: description: >- Toggle whether the alert produces matches. False pauses; true resumes. type: boolean notifications: items: $ref: '#/components/schemas/AlertNotificationChannel' maxItems: 20 minItems: 1 type: array title: maxLength: 200 minLength: 1 type: string type: object Alert: additionalProperties: false properties: created_at: format: date-time type: string created_by: $ref: '#/components/schemas/Creator' description: >- User who created the alert. Null when the alert was created via an API key. delivery_cadence: description: >- 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. type: string description: type: string entities: items: $ref: '#/components/schemas/AlertEntity' type: - array - 'null' filters: $ref: '#/components/schemas/AlertFilters' description: >- 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). id: type: string is_active: description: >- Whether the alert produces matches. Disabled alerts retain history but accumulate no new matches until re-enabled. type: boolean kind: description: >- 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. enum: - ENTITY_MENTION - PODCAST_SPEAKER type: string notifications: items: $ref: '#/components/schemas/AlertNotificationChannel' type: - array - 'null' project_id: type: string title: type: string updated_at: format: date-time type: string required: - id - project_id - title - kind - delivery_cadence - is_active - entities - notifications - created_at - updated_at type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object AlertEntity: additionalProperties: false properties: entity_id: type: string entity_type: enum: - PERSON - COMPANY - KNOWLEDGE_GRAPH_ENTITY type: string image_url: description: >- Image URL for the watched entity (headshot for PERSON, logo for COMPANY, image for KGE). Omitted from the response when no image is available. type: string name: description: >- Display name of the watched entity. Omitted from the response when the underlying record cannot be resolved (e.g. deleted). type: string required: - entity_type - entity_id type: object AlertFilters: additionalProperties: false properties: languages: description: >- Primary language tags the source episode must be in. Accepts a 2-3 letter primary tag (e.g. 'en', 'de', 'sma') and tolerates an optional 2-4 char region or script subtag for readability (e.g. 'pt-BR', 'zh-Hant'); matching is on the PRIMARY tag only, so '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. Codes are compared case-insensitively; the API echoes back the canonical primary-tag form. items: type: string type: - array - 'null' relevance: description: >- EVERYTHING (the 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 (knowledge-graph name collisions, e.g. the podcast 'Truckie' for an alert on the town 'Truckee') are globally suppressed before any filter runs. enum: - EVERYTHING - RELEVANT type: string source_popularity: description: >- ANY (the 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. REPLACES (not intersects with) the default appearance set the alert matches against. Default when omitted is GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER — HOST is intentionally excluded because hosting the show isn't an appearance. Setting ['HOST'] flips that — only HOST appearances match. Setting ['GUEST'] alone narrows further. Sending this on an ENTITY_MENTION alert returns 422 — the wire layer can't tell at validation time, so the handler boundary rejects it once the parent kind is known. Persisted in canonical uppercase form (e.g. 'GUEST'); raw STT/LLM labels like CALLER or REPORTER are not accepted because podcast_episode_speakers.role canonicalizes to the buckets above at write time. items: enum: - HOST - GUEST - PANELIST - CORRESPONDENT - AUDIENCE - SOUNDBITE_SPEAKER type: string type: - array - 'null' type: object AlertNotificationChannel: additionalProperties: false properties: created_by: $ref: '#/components/schemas/Creator' description: User who added this destination. Server-populated. email: description: Required when type=EMAIL. format: email type: string id: type: string slack_channel_id: description: >- Required when type=SLACK. Slack vendor channel id (e.g. C01234XYZ for public channels, G... for private channels). Must be a channel returned by GET /v1/projects/{projectId}/slack/connections/{id}/channels. type: string slack_channel_name: description: >- Optional. Display label for the destination channel. The server overwrites this from the cached slack_channels row on save, so clients do not need to supply it. type: string slack_connection_id: description: >- Required when type=SLACK. The Slack workspace connection that owns the channel. The connection's surface must match the monitor's CreatedVia (a PLATFORM monitor cannot pick a Radar connection). type: string type: description: >- Delivery channel type. EMAIL writes to email; SLACK posts a message to a channel in a connected Slack workspace; WEBHOOK POSTs a signed JSON payload to a configured webhook connection. enum: - EMAIL - SLACK - WEBHOOK type: string webhook_connection_id: description: >- Required when type=WEBHOOK. The webhook connection that receives the signed payload. type: string required: - type type: object Creator: additionalProperties: false properties: id: description: Creator's user ID type: string name: description: Creator's display name type: string required: - id - name type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ````