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, use explicit entity IDs.

REST

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

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.

Example arguments:

{"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.