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

# Watchlists API — Save and Organize Markets

> Create and manage watchlists to organize canonical questions and platform markets you want to follow. Requires a session JWT or SIWE wallet authentication.

Watchlists let you group canonical questions and platform markets you want to monitor closely. Each watchlist belongs to your authenticated account — whether you signed in with email and password or connected a wallet via SIWE. You can create multiple watchlists to segment different strategies or research topics.

## Authentication

A session JWT or SIWE session cookie is required for all watchlist endpoints:

```
Authorization: Bearer <your_jwt>
```

## Endpoints

| Method   | Path                                                | Description                    |
| -------- | --------------------------------------------------- | ------------------------------ |
| `GET`    | `/api/v1/watchlists`                                | List all your watchlists       |
| `POST`   | `/api/v1/watchlists`                                | Create a watchlist             |
| `GET`    | `/api/v1/watchlists/{id}`                           | Get a watchlist with its items |
| `PATCH`  | `/api/v1/watchlists/{id}`                           | Rename a watchlist             |
| `DELETE` | `/api/v1/watchlists/{id}`                           | Delete a watchlist             |
| `POST`   | `/api/v1/watchlists/{id}/items`                     | Add an item to a watchlist     |
| `DELETE` | `/api/v1/watchlists/{watchlist-id}/items/{item-id}` | Remove an item                 |

***

## List watchlists

```
GET https://api.predexy.com/api/v1/watchlists
```

Returns all watchlists associated with your account.

### Example request

```bash cURL theme={null}
curl https://api.predexy.com/api/v1/watchlists \
  -H "Authorization: Bearer <your_jwt>"
```

### Sample response

```json theme={null}
{
  "data": [
    {
      "id": "wl-3fa85f64-5717-4562-b3fc-000000000001",
      "name": "Crypto Q4",
      "item_count": 12,
      "created_at": "2026-03-10T09:00:00Z"
    },
    {
      "id": "wl-3fa85f64-5717-4562-b3fc-000000000002",
      "name": "US Politics",
      "item_count": 5,
      "created_at": "2026-04-01T12:00:00Z"
    }
  ]
}
```

***

## Create a watchlist

```
POST https://api.predexy.com/api/v1/watchlists
```

Creates a new watchlist with the given name.

### Request body

<ParamField body="name" type="string" required>
  Display name for the watchlist.
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.predexy.com/api/v1/watchlists \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Crypto Q4"}'
```

### Sample response

```json theme={null}
{
  "data": {
    "id": "wl-3fa85f64-5717-4562-b3fc-000000000001",
    "name": "Crypto Q4",
    "item_count": 0,
    "created_at": "2026-04-25T15:00:00Z"
  }
}
```

***

## Add an item to a watchlist

```
POST https://api.predexy.com/api/v1/watchlists/{id}/items
```

Adds a canonical question or platform market to the watchlist. You can provide either `canonical_question_id`, `market_id`, or both.

### Request body

<ParamField body="canonical_question_id" type="string">
  UUID of a canonical question to add. Provide this to track a question across all platforms.
</ParamField>

<ParamField body="market_id" type="string">
  UUID of a specific platform market to add. Provide this to track a single venue's listing.
</ParamField>

<Note>
  Watchlists are scoped to your authenticated account. If you authenticate via wallet (SIWE), your watchlists are tied to that wallet address. If you authenticate via email, they are tied to your developer account. The two are separate and do not merge.
</Note>