# Events

> Event feed, event detail, deduped group lookup, and the public SSE stream.

## GET /v1/events

List DeFi events with filters, cursor-style metadata, and full-text search.

### Query Parameters

| Parameter         | Type   | Default     | Description                                             |
| ----------------- | ------ | ----------- | ------------------------------------------------------- |
| page              | number | 1           | Page number                                             |
| limit             | number | 20          | Results per page                                        |
| eventType         | string | -           | Event type such as `Incident` or `DepositabilityChange` |
| severity          | string | -           | `Critical`, `Warning`, or `Info`                        |
| protocolId        | string | -           | Protocol ID                                             |
| curatorId         | string | -           | Curator ID                                              |
| chainId           | string | -           | Chain ID                                                |
| incidentSeverity  | string | -           | `minor` or `major`                                      |
| remediationStatus | string | -           | `resolved` or `unresolved`                              |
| search            | string | -           | Full-text search on title and description               |
| excludeSource     | string | -           | Exclude a source such as `peg-monitor`                  |
| sortBy            | string | occurred_at | Sort field                                              |
| sortOrder         | string | desc        | `asc` or `desc`                                         |
| daysBack          | string | adaptive    | Lookback window, capped at 730 days                     |

### Example

```bash
curl "https://api.philidor.io/v1/events?severity=Critical&limit=5"
```

### Response

```json
{
  "data": [
    {
      "id": "42",
      "event_type": "Incident",
      "severity": "Critical",
      "title": "Vault incident",
      "description": "Incident summary",
      "occurred_at": "2026-07-01T12:00:00Z",
      "protocol_id": "morpho",
      "protocol_name": "Morpho",
      "chain_id": 1,
      "chain_name": "Ethereum",
      "curator_id": "gauntlet",
      "curator_name": "Gauntlet",
      "incident_severity": "major",
      "loss_amount_usd": null,
      "remediation_status": "unresolved",
      "links": [],
      "occurrence_count": 1,
      "group_key": "incident:morpho:42"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "hasMore": false
  }
}
```

---

## GET /v1/events/\{id\}

Get one event with affected vaults.

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| id        | string | Event ID    |

### Example

```bash
curl https://api.philidor.io/v1/events/42
```

### Response

```json
{
  "data": {
    "id": "42",
    "event_type": "Incident",
    "severity": "Critical",
    "title": "Vault incident",
    "affected_vaults": [
      {
        "vault_id": "morpho-1-0x...",
        "vault_name": "Gauntlet USDC Core",
        "tvl_usd": 125000000,
        "chain_id": 1,
        "address": "0x..."
      }
    ]
  }
}
```

---

## GET /v1/events/group/\{groupKey\}

Return the current representative for a deduped event group. This helps clients recover when a grouped event is retracted.

### Example

```bash
curl https://api.philidor.io/v1/events/group/rating-change:morpho:2026-06-22
```

### Response

Same shape as a single event list item.

---

## GET /v1/events/stream

Open a public Server-Sent Events stream. No key is required.

The stream sends a `ready` frame, then event frames named `published`, `promoted`, or `retracted`. Heartbeat comments are sent every 20 seconds by the current implementation. The stream allows up to 5 concurrent connections per IP and returns `429` after that cap.

### Query Parameters

| Parameter | Type   | Default | Description           |
| --------- | ------ | ------- | --------------------- |
| vaultId   | string | -       | Optional vault filter |

### Example

```javascript
const stream = new EventSource('https://api.philidor.io/v1/events/stream');

stream.addEventListener('published', (event) => {
  const row = JSON.parse(event.data);
  console.log(row.title);
});
```

### Response

```text
event: ready
data: {"vaultId":null}

id: 42
event: published
data: {"id":42,"title":"Vault incident"}
```