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

# Watch + alerts API

> Watched objects, alert rules, webhook endpoints, and delivery records — the full HTTP surface behind the watchlist + alerts ecosystem.

Endpoints for the watchlist + alerts ecosystem. See [Watchlist + alerts](/build/watchlist-alerts) for the conceptual model.

## Watched objects

| Endpoint | Purpose |
| - | - |
| `GET /api/watch` | List watched objects |
| `POST /api/watch` | Add (by ticker / URL / query / text) |
| `POST /api/watch/identify` | Resolve free-text to a canonical watched object |
| `GET /api/watch/{id}` | Detail |
| `PATCH /api/watch/{id}` | Update |
| `DELETE /api/watch/{id}` | Remove |
| `POST /api/watch/{id}/refresh` | Force re-evaluation now |

## Alert rules

| Endpoint | Purpose |
| - | - |
| `GET /api/alert-rules` | List rules |
| `POST /api/alert-rules` | Create rule |
| `GET /api/alert-rules/{id}` | Detail |
| `PATCH /api/alert-rules/{id}` | Update (pause/archive included) |
| `DELETE /api/alert-rules/{id}` | Delete |
| `POST /api/alert-rules/{id}/test` | Test fire |

Rule body:

```json theme={null}
{
  "watchedObjectId": "wo_...",
  "condition": "price_above",
  "threshold": 65,
  "windowSeconds": 3600,
  "channels": [{ "type": "webhook", "endpointId": "we_..." }],
  "status": "active"
}
```

Conditions: `price_above`, `price_below`, `econ_release`, `gov_action`, `semantic_match`.

## Webhook endpoints

| Endpoint | Purpose |
| - | - |
| `GET /api/webhook-endpoints` | List endpoints |
| `POST /api/webhook-endpoints` | Create |
| `PATCH /api/webhook-endpoints/{id}` | Update |
| `DELETE /api/webhook-endpoints/{id}` | Delete |
| `POST /api/webhook-endpoints/{id}/test` | Test delivery |

Body:

```json theme={null}
{ "url": "https://your.app/sf-hook", "label": "ops", "events": ["alert.fired"] }
```

Returns the endpoint id (`we_...`) and signing secret. Store the secret — it isn't shown again.

## Alert deliveries

| Endpoint | Purpose |
| - | - |
| `GET /api/alert-deliveries` | List recent deliveries |

Each delivery has `id`, `ruleId`, `endpointId`, `status` (`pending`, `delivered`, `failed`, `paused`), `dedupeKey`, `attempts`, `lastResponseStatus`, `lastError`.

## Authentication

API key (`sf_live_...`) via `Authorization: Bearer ...`. User-owned workflow state is scoped to the authenticated user.

## Compatibility

Older integrations may have used older watchlist or alert paths. New integrations should use `/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints`, and `/api/alert-deliveries`.

## See also

<CardGroup cols={2}>
  <Card title="Watchlist + alerts" href="/build/watchlist-alerts">
    Conceptual model and CLI walkthrough.
  </Card>

  <Card title="Webhook receiver" href="/integrations/webhook-receiver">
    Receiver code samples.
  </Card>

  <Card title="Webhook events" href="/reference/webhook-events">
    Per-event payload schemas.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.