> ## 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; the entities list, when provided, replaces the watched entity (exactly one). ## 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 x-guidance: >- Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; agent onboarding recipe: https://api.particle.pro/auth.md. 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; the entities list, when provided, replaces the watched entity (exactly one). 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: description: >- 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. items: $ref: '#/components/schemas/AlertEntity' maxItems: 1 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. Input casing is not significant — 'guest' and 'GUEST' are the same value — and the filter is persisted and echoed back in canonical uppercase form. 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. Any active connection belonging to the alert's project is accepted, whichever surface installed it, so an alert created in one app can be managed from the other. 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 ````