> ## 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>