> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Recent competitive intelligence alerts for your account.

Returns recent alerts, newest first.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys.
</ParamField>

Required scope: `alerts:read`.

## GET /api/v1/me/alerts

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/v1/me/alerts?limit=20&unread=true" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```
</RequestExample>

Query parameters:

| Parameter | Type    | Default | Description                                                                                         |
| --------- | ------- | ------- | --------------------------------------------------------------------------------------------------- |
| `limit`   | integer | `50`    | Alerts per page, max `200`                                                                          |
| `unread`  | boolean | `false` | Only return unread alerts                                                                           |
| `type`    | string  | -       | Filter by alert type, such as `rating_drop`, `review_surge`, `price_change`, or `trend_opportunity` |

```json theme={null}
{
  "count": 1,
  "alerts": [
    {
      "id": "94d92b0e-0a92-46bb-86c3-6f8f9d3dafbf",
      "type": "rating_drop",
      "title": "Competitor rating dropped",
      "description": "A tracked competitor rating dropped.",
      "recommendation": "Watch for repeated complaints and adjust your response playbook.",
      "severity": "opportunity",
      "competitorId": "comp_xyz",
      "competitorName": "Rival Pizza",
      "createdAt": "2026-04-27T08:14:22Z",
      "read": false
    }
  ]
}
```

## PATCH /api/v1/me/alerts/:id

Marks an alert as read or unread.

Required scope: `alerts:write`.

```bash theme={null}
curl -X PATCH "https://app.neariq.io/api/v1/me/alerts/94d92b0e-0a92-46bb-86c3-6f8f9d3dafbf" \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "read": true }'
```

```json theme={null}
{
  "alert": {
    "id": "94d92b0e-0a92-46bb-86c3-6f8f9d3dafbf",
    "read": true
  }
}
```