# Watch

URL: /business/nouns/watch · Id: `noun:watch`

> A Watch is an outbound subscription that delivers the Events a selector matches to a URL, signed, retried, and replayable.

A Watch is an outbound subscription that delivers the [Events](/business/nouns/event) a selector matches to a URL, signed, retried, and replayable.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `selector` | `string` | Yes | The Event selector, such as `Order.placed`. |
| `url` | `url` | Yes | Where deliveries go. |
| `payload` | `string` | No | One of `full`, or `thin`: the record as the Action left it, or only its versioned address. The default is full. |

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/watches/watch_1",
  "$type": "Watch",
  "selector": "Example selector",
  "url": "https://patentpad.com",
  "payload": "full"
}
```

## Relationships
- <a id="rel-delivers"></a>A Watch **delivers** many [Events](/business/nouns/event): a Watch delivers each matching [Event](/business/nouns/event) to its URL, signed, retried and replayable. `delivers`, inverse [`deliveredBy`](/business/nouns/event#rel-delivered-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Watch.pause](/business/nouns/watch/pause) | Pause stops a Watch delivering while its Events keep queuing; the platform pauses a Watch whose deliveries fail for three days. | [Worker](/business/nouns/worker) | [`Watch.paused`](/business/events/Watch.paused) | None. |
| [Watch.replay](/business/nouns/watch/replay) | Replay redelivers a Watch’s Events from a chosen point, signed as they were the first time. | [Quality Lead](/agents/quality/quality-lead) | [`Watch.replayed`](/business/events/Watch.replayed) | None. |
| [Watch.resume](/business/nouns/watch/resume) | Resume restarts a paused Watch and delivers the Events it held, oldest first. | [Worker](/business/nouns/worker) | [`Watch.resumed`](/business/events/Watch.resumed) | None. |
| [Watch.rotate](/business/nouns/watch/rotate) | Rotate issues a new signing secret for a Watch and signs with both secrets until the old one expires. | [Worker](/business/nouns/worker) | [`Watch.rotated`](/business/events/Watch.rotated) | None. |
| <a id="create"></a>[Watch.create](/business/nouns/watch/create) | Creates a Watch. Inherited from [Noun](/business/nouns/noun). | None. | `Watch.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Watch.get](/business/nouns/watch/get) | Returns one Watch by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Watch.list](/business/nouns/watch/list) | Returns Watches, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Watch.update](/business/nouns/watch/update) | Changes the given properties of a Watch. Inherited from [Noun](/business/nouns/noun). | None. | `Watch.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Watch.delete](/business/nouns/watch/delete) | Deletes a Watch; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Watch.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Watch.create` | Yes | Yes | Yes | No |
| `Watch.get` | Yes | Yes | Yes | Yes |
| `Watch.list` | Yes | Yes | Yes | Yes |
| `Watch.update` | Yes | Yes | Yes | No |
| `Watch.delete` | Yes | Yes | Yes | No |
| `Watch.pause` | Yes | Yes | Yes | No |
| `Watch.replay` | Yes | Yes | Yes | No |
| `Watch.resume` | Yes | Yes | Yes | No |
| `Watch.rotate` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Replay the latest watch.
```

**API**

```bash
curl -X POST https://api.sb/petpantry.shop/watches/watch_1/replay \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-22T12:00:00Z"}'
```

```json
{
  "api": "https://api.sb/petpantry.shop",
  "watch": {
    "$id": "https://api.sb/petpantry.shop/watches/watch_1",
    "$type": "Watch",
    "selector": "Example selector",
    "url": "https://petpantry.shop"
  },
  "action": {
    "$id": "https://api.sb/petpantry.shop/actions/action_1",
    "operation": "Watch.replay",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/petpantry.shop/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const watch = await $.Watch.replay({ watch: 'watch_1', from: '2026-10-22T12:00:00Z' })
```

**CLI**

```bash
npx startup-builder do Watch.replay --json '{"watch":"watch_1","from":"2026-10-22T12:00:00Z"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Watch.replay({ watch: 'watch_1', from: '2026-10-22T12:00:00Z' })"
  }
}
```

## Example
A dental group registers a Watch for `Reminder.confirmed` [Events](/business/nouns/event) to `https://hooks.brightsmiles.dental/reminders`. Each delivery is signed, retried on failure, and replayable after an outage.