# Watchlists

Manage the same personal company lists through the web app, REST and MCP.

Source: <https://docs.finbar.com/api-mcp/watchlists>

Watchlists have stable IDs and revisions. The web app, public API and MCP read
and update the same lists. Names are display labels, so renaming a list preserves
its members, email preference and webhook subscriptions. Duplicate names are
allowed; always address a list by its ID.

Interactive users access their own lists. A personal machine credential accesses
the owner of its billing account; actions remain attributed to the machine.
Team machine credentials return `403 watchlist_access_denied`. For team
[webhook subscriptions](https://docs.finbar.com/api-mcp/webhooks.md), use explicit entity IDs.

## REST

Use `read` for reads. Request `read` and `write` to create or change lists.

| Method and path                                            | Input                                                            |
| ---------------------------------------------------------- | ---------------------------------------------------------------- |
| `GET /v1/watchlists`                                       | Optional `cursor`, `limit` (1–100, default 50)                   |
| `GET /v1/watchlists/{watchlist_id}`                        | Stable UUID                                                      |
| `POST /v1/watchlists`                                      | `name`, optional `entity_ids`; optional `Idempotency-Key` header |
| `PATCH /v1/watchlists/{watchlist_id}`                      | `name` and current `revision`                                    |
| `DELETE /v1/watchlists/{watchlist_id}?revision=...`        | Current revision                                                 |
| `POST /v1/watchlists/{watchlist_id}/members`               | `entity_ids` to add                                              |
| `DELETE /v1/watchlists/{watchlist_id}/members/{entity_id}` | Member to remove                                                 |

```bash
curl --fail-with-body --silent --show-error \
  'https://api.finbar.com/v1/watchlists' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: earnings-list-v1' \
  --data '{"name":"Earnings automation","entity_ids":["O-YOUR_ENTITY_ID"]}'
```

Creation returns the watchlist with `id`, `name`, `revision`, `entity_ids`,
`created_at` and `updated_at`. Names must contain 1–200 characters. Each create or batch membership request accepts
up to 1,000 company IDs. Repeated membership additions/removals
are safe and preserve the membership state; resolve company IDs through entity
search if needed.

A stale update/delete revision or a collection change during pagination returns
`409 resource_changed`. Fetch the current state before retrying so concurrent
web edits and automation do not overwrite each other. Creation idempotency keys
retain the original response for 24 hours; reusing a key with different input
returns `409 idempotency_conflict`.

Watchlist operations share an account limit of 60 requests per minute, burst 10,
and do not consume document-read quota.

## MCP: one tool

Use `manage_watchlists` with an `action`. Its schema selects the fields allowed
for that action; irrelevant arguments are rejected.

| Action           | Arguments                                        | Required scope  |
| ---------------- | ------------------------------------------------ | --------------- |
| `list`           | Optional `cursor`, `limit`                       | `read`          |
| `get`            | `watchlist_id`                                   | `read`          |
| `create`         | `name`; optional `entity_ids`, `idempotency_key` | `read`, `write` |
| `update`         | `watchlist_id`, `revision`, `name`               | `read`, `write` |
| `delete`         | `watchlist_id`, `revision`                       | `read`, `write` |
| `add_members`    | `watchlist_id`, `entity_ids`                     | `read`, `write` |
| `remove_members` | `watchlist_id`, `entity_ids`                     | `read`, `write` |

Example arguments:

```json
{"action":"create","name":"Earnings automation","entity_ids":["O-YOUR_ENTITY_ID"],"idempotency_key":"earnings-list-v1"}
```

The tool returns `watchlist` for individual operations, `items` and an optional
`next_cursor` for lists, or `deleted: true` for deletion. Webhook setup uses the
REST API; it is independent of watchlist email notifications.