# Alerts API

Base URL: `https://api.dongfeng-systems.org`

---

## Create Alert

**POST** `/api/alerts/create`

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | string | yes | User identifier |
| `symbol` | string | yes | Ticker symbol (e.g. AAPL) |
| `alertType` | string | yes | One of the alert types below |
| `parameters` | string (JSON) | yes | JSON string with type-specific parameters |

### Alert Types & Parameters

**`price_threshold`** — Triggers when price crosses a target value.

```json
{ "direction": "above", "target": 200.0 }
```

| Param | Type | Description |
|---|---|---|
| `direction` | string | `"above"` or `"below"` |
| `target` | number | Target price |

**`percent_change`** — Triggers when daily percent change from previous close crosses a threshold.

```json
{ "percentThreshold": 5.0 }
```

| Param | Type | Description |
|---|---|---|
| `percentThreshold` | number | Positive triggers on gains, negative on losses |

**`price_spike`** — Triggers when price moves sharply within a rolling time window.

```json
{ "percentChange": 3.0, "windowMinutes": 10 }
```

| Param | Type | Description |
|---|---|---|
| `percentChange` | number | Minimum percent move to trigger |
| `windowMinutes` | number | Rolling window size in minutes (default: 15) |

**`trailing_price`** — Tracks a price extreme and triggers on reversal.

```json
{ "direction": "bullish", "trailPercent": 5.0 }
```

| Param | Type | Description |
|---|---|---|
| `direction` | string | `"bullish"` (triggers on drop from peak) or `"bearish"` (triggers on rise from trough) |
| `trailPercent` | number | Percent reversal from extreme to trigger |

### Example

```bash
curl -X POST https://api.dongfeng-systems.org/api/alerts/create \
  -H "Content-Type: application/json" \
  -d '{
    "username": "joe",
    "symbol": "AAPL",
    "alertType": "price_threshold",
    "parameters": "{\"direction\": \"above\", \"target\": 200.0}"
  }'
```

**Response:**

```json
{
  "id": 1,
  "username": "joe",
  "symbol": "AAPL",
  "alertType": "price_threshold",
  "parameters": "{\"direction\": \"above\", \"target\": 200.0}",
  "lastState": "{}",
  "isTriggered": false,
  "createdAt": "2026-03-20T12:00:00Z"
}
```

---

## List Alerts

**GET** `/api/alerts/list?username={username}`

Returns all alerts for a user (both active and triggered).

```bash
curl "https://api.dongfeng-systems.org/api/alerts/list?username=joe"
```

---

## List Triggered Alerts

**GET** `/api/alerts/triggered?username={username}`

Returns only triggered alerts for a user.

```bash
curl "https://api.dongfeng-systems.org/api/alerts/triggered?username=joe"
```

---

## Delete Alert

**DELETE** `/api/alerts/delete?username={username}&id={alertId}`

Deletes an alert. Only the owning user can delete it.

```bash
curl -X DELETE "https://api.dongfeng-systems.org/api/alerts/delete?username=joe&id=1"
```

**Response:**

```json
{ "success": true }
```