Manage watchlists

A watchlist is a named collection of instruments you want to track. This guide walks through managing your own (user) watchlists: listing them, creating one, fetching it by name, replacing it, and deleting it. tastytrade also publishes read-only public watchlists and pairs watchlists that any client can fetch.

All requests go to the sandbox base URL https://api.cert.tastyworks.com or production https://api.tastyworks.com. Every request must send a valid OAuth access token (Authorization: Bearer <token>, minted via POST /oauth/token, 15-minute expiry) and a User-Agent: product/version header (see Get started). JSON keys are dasherized (for example watchlist-entries, instrument-type, order-index).

1. List your watchlists

GET /watchlists returns every watchlist for the authenticated user.

curl https://api.cert.tastyworks.com/watchlists \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-app/1.0.0"

2. Create a watchlist

POST /watchlists creates a watchlist. The request body requires name and watchlist-entries. Each entry requires a symbol; instrument-type is optional but recommended so the symbol resolves unambiguously. See Instruments and symbology for valid symbol formats and instrument types. You may also set an optional group-name and order-index (defaults to 9999).

{
  "name": "Tech Megacaps",
  "group-name": "Sectors",
  "order-index": 10,
  "watchlist-entries": [
    { "symbol": "AAPL", "instrument-type": "Equity" },
    { "symbol": "MSFT", "instrument-type": "Equity" }
  ]
}

curl -X POST https://api.cert.tastyworks.com/watchlists \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-app/1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Megacaps",
    "watchlist-entries": [
      { "symbol": "AAPL", "instrument-type": "Equity" },
      { "symbol": "MSFT", "instrument-type": "Equity" }
    ]
  }'

A successful create returns 201 Created with the stored watchlist. Creating is not idempotent, so retrying after a network error may produce a duplicate — confirm with a list call before retrying. See Idempotency and retries.

3. Get a watchlist by name

GET /watchlists/{watchlist_name} returns a single watchlist. URL-encode the name if it contains spaces (for example Tech%20Megacaps).

curl "https://api.cert.tastyworks.com/watchlists/Tech%20Megacaps" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-app/1.0.0"

4. Update (replace) a watchlist

PUT /watchlists/{watchlist_name} replaces all properties of the watchlist. This is a full replacement, not a merge: send the complete watchlist-entries array you want to keep — entries omitted from the body are removed. The body uses the same shape as create and requires name and watchlist-entries.

curl -X PUT "https://api.cert.tastyworks.com/watchlists/Tech%20Megacaps" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-app/1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Megacaps",
    "watchlist-entries": [
      { "symbol": "AAPL", "instrument-type": "Equity" },
      { "symbol": "MSFT", "instrument-type": "Equity" },
      { "symbol": "NVDA", "instrument-type": "Equity" }
    ]
  }'

To rename a watchlist, set a new name in the body. PUT returns 200 OK with the updated watchlist.

5. Delete a watchlist

DELETE /watchlists/{watchlist_name} removes the watchlist and returns 200 OK with the deleted watchlist.

curl -X DELETE "https://api.cert.tastyworks.com/watchlists/Tech%20Megacaps" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-app/1.0.0"

Public and pairs watchlists (read-only)

These endpoints are shared by tastytrade and cannot be modified:

Operation	Endpoint
List public watchlists	`GET /public-watchlists`
Get one public watchlist	`GET /public-watchlists/{watchlist_name}`
List pairs watchlists	`GET /pairs-watchlists`
Get one pairs watchlist	`GET /pairs-watchlists/{pairs_watchlist_name}`

GET /public-watchlists accepts an optional counts-only query parameter (boolean, default false) to return entry counts instead of full entries.

Error handling

Watchlist endpoints use standard HTTP status codes — 422 for malformed or invalid bodies, 401/403 for auth problems, 404 for an unknown watchlist name, and 429 when you are rate limited (see Rate limits and backoff). See Error reference for the response shape.