Watchlists
Reusable lists of companies or people that signal agents watch.
A watchlist is a reusable, named list of canonical companies or people that you bind to a signal agent. The agent then surfaces interactions involving the list's members. Watchlists are workspace-scoped and exist independently of any agent — one list can be bound to several agents over time.
Kind is derived from type
Every list has an immutable type, set at creation. The type determines the list kind (company vs people) — you never declare the kind yourself:
type | kind | members |
|---|---|---|
competitor | company | companies |
partner | company | companies |
customer | company | companies |
influencer | profile | people |
champion | profile | people |
type cannot be changed after creation (it would move the list across kinds). title and description are editable.
Endpoints
Single-list endpoints are keyed by a compound /:kind/:watchlist_id path, where kind is company or profile and matches the list's immutable type. The company and profile collections have independent id sequences, so the kind disambiguates which one a watchlist_id refers to (no cross-kind id collision). The collection endpoints take no kind.
- Create watchlist:
POST /api/v2/watchlists - List watchlists:
GET /api/v2/watchlists - Get watchlist:
GET /api/v2/watchlists/:kind/:watchlist_id - Update watchlist:
PUT /api/v2/watchlists/:kind/:watchlist_id - Delete watchlist:
DELETE /api/v2/watchlists/:kind/:watchlist_id - Add entities:
POST /api/v2/watchlists/:kind/:watchlist_id/entities - List entities:
GET /api/v2/watchlists/:kind/:watchlist_id/entities - Remove entity:
DELETE /api/v2/watchlists/:kind/:watchlist_id/entities/:entity_id
Binding to an agent
Bind a list to an agent with the watchlist_kind and watchlist_id fields together on Create agent or Update agent. An agent watches at most one list; pass both watchlist_kind: null and watchlist_id: null on update to unbind.