---
title: "Add Cards to Price Watchlist"
method: POST
path: "/v1/cards/watchlist"
tags: ["Watchlist"]
---

# Add Cards to Price Watchlist

`POST /v1/cards/watchlist`

Add card + grade combinations to your price watchlist.

Watched cards' price changes flow through `POST /v1/cards/watchlist-updates`.
Omit `grade_label` to watch **all grades** for a card (one watchlist slot).
Adding is idempotent: entries already on the list return success with a note.

**Request fields:**

- `items` — list, required. 1-100 entries per request.
- `items[].card_id` — string, required. CardHedge card ID (from
  `card-search`, `card-match`, etc.), or `"*"` for watch-all
  (Enterprise only).
- `items[].grade_label` — string, optional. Grade exactly as used across
  the API (e.g. `"PSA 10"`, `"Raw"`). Omit to watch all grades.

## Behavior

- **Always returns HTTP 200 with per-item results** — an unknown `card_id`
  or an invalid item fails individually without affecting the rest of the
  batch. Check `results[].success` and `results[].error`.
- **Idempotent:** re-adding an existing entry succeeds with
  `note: "already on watchlist"` and does not consume another slot.
- **Redundancy notes:** adding a specific grade when an all-grades entry
  already covers that card succeeds, with a note saying so.
- **Tier caps:** total watchlist size is capped by subscription tier
  (Free 100 / Pro 1,000 / Enterprise 10,000). Exceeding the cap fails the
  whole request with HTTP 400 — remove entries or upgrade.
- `watchlist_size` and `watchlist_cap` in the response tell you where you
  stand.

## Example

```bash
curl -X POST -H "X-API-Key: your-api-key"          -H "Content-Type: application/json"          -d '{"items": [{"card_id": "1586812246197x228181943611293700", "grade_label": "PSA 10"}]}'          "https://api.cardhedger.com/v1/cards/watchlist"
```

## Request body

- WatchlistAddRequest
  - `items` WatchlistItemIn[], required
    - `card_id` string, required — CardHedge card ID, or '*' to watch the entire catalog (enterprise tier only; '*' cannot carry a grade_label).
    - `grade_label` string, nullable — Grade exactly as used across the API (e.g. 'PSA 10', 'Raw'). Omit to watch all grades for the card.

## Response `200`

Per-item results (always 200, even on partial failure)

- WatchlistAddResponse
  - `results` WatchlistItemResult[], required
    - `card_id` string, required
    - `grade_label` string, nullable
    - `success` boolean, required
    - `error` string, nullable
    - `note` string, nullable
  - `total_requested` integer, required
  - `total_added` integer, required
  - `watchlist_size` integer, required
  - `watchlist_cap` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) · [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardhedger/card-hedge-api/revisions/497390569396/schema)