> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchlists API

> Create and manage named sets of assets tied to your account, then reuse them to scope queries across the Blockworks API.

A watchlist is a named set of assets tied to your account. Group the assets you actually care
about once, then reuse that grouping to drive dashboards, alerts, portfolio views, or any
client that needs a stable list of assets rather than an ad hoc query.

Watchlists are the read/write exception in an otherwise read-only surface. Everything else on
the Blockworks API answers questions about the market; these endpoints let you create, update,
and delete state that belongs to your account.

## Base URL and authentication

Watchlist endpoints live under `/user-management/v1` on the shared Blockworks API host:

```
https://api.blockworks.com/user-management/v1/watchlists
```

Every request requires an API key in the `X-Blockworks-API-Key` header. See
[Authentication](/getting-started/authentication) for details and for where to get a key.

```bash theme={null}
curl "https://api.blockworks.com/user-management/v1/watchlists" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"
```

Responses use the standard envelope:

```json theme={null}
{
  "error": null,
  "data": { }
}
```

## Shape of a watchlist

Each watchlist carries an `id`, a `title`, the `assetIds` it contains, and `createdAt` /
`updatedAt` timestamps. Assets are referenced by UUID, not by slug or symbol, so resolve the
identifiers you need from
[Asset Entities](/api-reference/data-api/assets/tabular-assets) before writing.

```json theme={null}
{
  "id": "8C25A83A",
  "title": "Layer 1 Protocols",
  "assetIds": [
    "1e31218a-e44e-4285-820c-8282ee222035",
    "21c795f5-1bfd-40c3-858e-e9d7e820c6d0"
  ],
  "createdAt": "2024-07-12T18:22:38.311119Z",
  "updatedAt": "2025-12-11T19:14:00.915569Z"
}
```

## Two ways to change assets

There are two write paths for the asset list, and picking the wrong one is the easiest
mistake to make:

* [Update Watchlist](/api-reference/monitoring/watchlists/update) replaces the whole
  `assetIds` array when you send one. Omit the field to leave assets untouched; send an empty
  array to clear them.
* [Update Watchlist Assets](/api-reference/monitoring/watchlists/update-assets) adds or
  removes specific assets and leaves the rest of the list alone.

## Use cases

* Track a portfolio or mandate as a named list instead of hardcoding asset IDs in your client.
* Let your users build their own asset groupings and sync them across your surfaces.
* Organize assets by sector, theme, or coverage responsibility, then scope reports to a list.
* Keep a stable set of assets to poll on a schedule as coverage changes.