Add Cards to Price 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

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"