# Update an alert subscription

`PATCH /v3/alerts/{id}`

Partial update: pause/resume, rename, change cadence, selector,
threshold, or destinations. Semantics are identical to creation.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AlertUpdate"
      },
      "examples": {
        "pause": {
          "summary": "Pause delivery",
          "value": {
            "status": "paused"
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "Updated subscription.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Alert"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Paused",
            "value": {
              "data": {
                "id": "66a10a2b1c9d440000d1e2f3",
                "status": "paused",
                "trigger": "intelligence.material",
                "selector": {
                  "followedProjects": true
                },
                "cadence": "hourly",
                "destinationIds": [
                  "66a10a2b1c9d440000aa0001"
                ],
                "createdAt": "2026-08-01T10:00:00Z",
                "updatedAt": "2026-08-05T05:10:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

## Referenced schemas

```json
{
  "AlertUpdate": {
    "type": "object",
    "description": "Partial update; omitted fields are unchanged.",
    "properties": {
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ]
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "$ref": "#/components/schemas/AlertCadence"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      }
    }
  },
  "AlertSelector": {
    "type": "object",
    "additionalProperties": false,
    "description": "What the subscription watches: the owner's followed Projects, the\ncurrently ranked cohort, a normalized keyword, or a qualifier-only cohort.\nExplicit per-Project and per-Topic id lists are not yet supported\nand will join additively.\n",
    "properties": {
      "followedProjects": {
        "type": "boolean",
        "description": "Only the owner's followed Projects. Mutually exclusive with the ranked Project scopes."
      },
      "trendingProjects": {
        "type": "boolean",
        "description": "Only Projects in the current Trend ranking. Mutually exclusive with `followedProjects`."
      },
      "keyword": {
        "type": "string",
        "minLength": 2,
        "maxLength": 64,
        "description": "Normalized once at save time; matched case-insensitively against source-derived text."
      },
      "qualifiers": {
        "$ref": "#/components/schemas/AlertQualifiers"
      }
    }
  },
  "AlertQualifiers": {
    "type": "object",
    "description": "Filter qualifiers; each list holds at most 20 values.\n`grades`, `sentiments`, `clusterIds`, `maxRank`, and\n`hasOfficialSource` qualify `intelligence.material` subscriptions;\n`chains` qualifies `rank.entered`; `categories` and `assetTypes`\nqualify both.\n",
    "properties": {
      "categories": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "grades": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Grade"
        }
      },
      "sentiments": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "assetTypes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "clusterIds": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "chains": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "maxRank": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Only intel on Projects at or above this rank in the Trend cohort."
      },
      "hasOfficialSource": {
        "type": "boolean"
      }
    }
  },
  "Grade": {
    "type": "string",
    "enum": [
      "chipped",
      "flawed",
      "cut",
      "polished",
      "flawless"
    ],
    "description": "Evidence grade of an Intel item, lowest to highest. Grades describe\nthe shape of the evidence, never the truth of the claim.\n"
  },
  "AlertCadence": {
    "type": "string",
    "enum": [
      "instant",
      "hourly",
      "every_12h",
      "daily"
    ],
    "description": "Chat delivery cadence. First event in a window delivers immediately;\nthe window bundles the rest. `instant` is subject to a per-day\nplatform safety ceiling.\n"
  },
  "Alert": {
    "type": "object",
    "required": [
      "id",
      "status",
      "trigger",
      "selector",
      "cadence",
      "destinationIds",
      "createdAt",
      "updatedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      },
      "trigger": {
        "$ref": "#/components/schemas/AlertTrigger"
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Top-N boundary; present only with `rank.entered`."
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ],
        "default": "trend",
        "description": "Ranking watched by `rank.entered`; omitted stored rows mean Trend."
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "$ref": "#/components/schemas/AlertCadence"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      },
      "createdAt": {
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "AlertTrigger": {
    "type": "string",
    "enum": [
      "intelligence.material",
      "rank.entered"
    ],
    "description": "The set of launch triggers."
  },
  "Meta": {
    "type": "object",
    "description": "Response metadata. Empty when nothing applies.",
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryMeta"
      },
      "versions": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Named component versions that shaped this response."
      }
    }
  },
  "HistoryMeta": {
    "type": "object",
    "description": "The history window applied to this response. Both fields are null when the account has no history limit.",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "earliestAvailableAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).