# Create alert configuration

`POST` `https://api.unusualwhales.com/api/alerts/configuration`

Creates a new alert configuration, or updates an existing one when `id` is given.

The alert filters can be given in one of two ways, but never both:
- `config`: a structured filter object for the given `noti_type`, the same configuration as returned by the alert configurations endpoint.
- `input`: a Query language expression. Use the Query language for complex filter expressions.

Before creating an alert fetch the available filters:
- `GET /api/alerts/filters` lists per alert type (`noti_type`) the filter fields that can be used in `config`, their accepted values, and whether your account can create alerts of that type.
- `GET /api/alerts/query/grammar` returns the Query language syntax. `GET /api/alerts/query/grammar?target=option_trade` the full field reference for one target.

Example with a structured `config`:
```json
{
  "name": "FED news",
  "noti_type": "news",
  "config": {"symbols": "all", "contains": ["FED"]}
}
```

Example with a Query language `input`:
```json
{
  "name": "Energy sector calls",
  "noti_type": "flow_alerts",
  "input": "add @energy where calls and volume > 100 and (dte > 10 or (dte = 0 and ticker = 'XOM'))"
}
```

The created alerts are delivered like the alerts created on [https://unusualwhales.com/custom-alerts](https://unusualwhales.com/custom-alerts)
and their triggers can be fetched from the alerts endpoint or streamed over the `custom_alerts` websocket channel.

The alerts and usage of the websocket are the easiest way to setup and get notified on anything that matches your filter configs.
The query language is a powerful tool to create complex configurations in a SQL like language.


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `config` | The configuration of an alert. | An alert configuration, there is no fixed schema for this as each alert will have a different configuration. |
| `created_at` | The creation timestamp |  |
| `dsl` | string | The canonical DSL representation when the configuration was created or updated using `input`. |
| `id` | The alert id |  |
| `name` | The name of the alert |  |
| `noti_type` | The type of the alert |  |
| `status` | The status of the alert |  |


## Example

### curl

```bash
curl -X POST "https://api.unusualwhales.com/api/alerts/configuration" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("POST", "/api/alerts/configuration", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": {
    "config": {
      "expression": {
        "op": "and",
        "terms": [
          {
            "sectors": [
              "Energy"
            ]
          },
          {
            "op": "and",
            "terms": [
              {
                "is_call": true
              },
              {
                "compare": {
                  "lhs": {
                    "field": "volume"
                  },
                  "op": "gt",
                  "rhs": {
                    "literal": "100"
                  }
                }
              }
            ]
          }
        ]
      },
      "symbols": "all"
    },
    "created_at": "2025-07-01T14:00:00Z",
    "dsl": "@Energy where calls and volume > 100",
    "id": "ebe24953-a0bf-4b4d-98be-14f721a1199a",
    "name": "Energy call sweeps",
    "noti_type": "flow_alerts",
    "status": "active"
  }
}
```