Watchlists

Your stock lists; a stock strategy can run on one.

List your watchlists #

GET /v1/watchlists app session

The caller's watchlists, by name: the same lists as the app's market watch.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/watchlists" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/watchlists",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/watchlists', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "6adf47df14d372ca8aa51ea7",
      "name": "Breakouts",
      "count": 2,
      "updated_at": "2026-10-26T12:30:23.476Z"
    }
  ],
  "error": null
}

Create a watchlist #

POST /v1/watchlists app session

Creates a named watchlist of up to 50 NSE / BSE cash equities (instrument tokens).

More about this

At most 50 watchlists per user.

Body fields

name string required

Display name, 1-60 characters after trimming, unique per user; not one of the app's built-in lists (Indices, Nifty 50, Nifty Bank).
symbols string[] | null

Members as instrument tokens (instrument_token), at most 50, in order. Every symbol added must be an NSE or BSE cash equity in today's instrument list. On create, absent means empty; on update, absent keeps the members, present replaces them (members kept from before are not checked again).

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
409	watchlist_name_taken	The caller already has a watchlist with this name.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

POST

curl -X POST "https://cirrus.pocketful.in/v1/watchlists" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Breakouts",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }'

import os

import requests

response = requests.post(
    "https://cirrus.pocketful.in/v1/watchlists",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "name": "Breakouts",
        "symbols": [
            "CT:EX:RELIANCE-EQ",
            "CT:EX:INFY-EQ",
        ],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/watchlists', {
  method: 'POST',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Breakouts",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 201

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea4"
  },
  "error": null
}

Read a watchlist #

GET /v1/watchlists/{watchlist_id} app session

A watchlist with each member's status today: tradable (a stock strategy on this list trades it), not_allowed (a cash equity automated strategies may not trade on this server), not_equity (an index or contract added from the market watch) or not_listed (not in today's instrument list).

Parameters

watchlist_id path · string required

Watchlist id.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea7",
    "name": "Breakouts",
    "symbols": [
      {
        "tradingsymbol": "RELIANCE-EQ",
        "stock": "RELIANCE",
        "exchange": "NSE",
        "name": "Reliance Industries",
        "status": "not_allowed",
        "instrument_token": "CT:EX:RELIANCE-EQ"
      },
      {
        "tradingsymbol": "INFY-EQ",
        "stock": "INFY",
        "exchange": "NSE",
        "name": "Infosys",
        "status": "not_allowed",
        "instrument_token": "CT:EX:INFY-EQ"
      }
    ],
    "tradable": 0,
    "updated_at": "2026-10-26T12:30:23.476Z"
  },
  "error": null
}

Rename a watchlist or replace its members #

PUT /v1/watchlists/{watchlist_id} app session

Sets the name and, when symbols is given, the members (kept members stay in place, new ones are added at the end).

More about this

Running stock strategies on this list pick the change up at their next entry: a stock taken out waits (watchlist_removed), its open trade keeps every exit.

Parameters

watchlist_id path · string required

Watchlist id.

Body fields

name string required

Display name, 1-60 characters after trimming, unique per user; not one of the app's built-in lists (Indices, Nifty 50, Nifty Bank).
symbols string[] | null

Members as instrument tokens (instrument_token), at most 50, in order. Every symbol added must be an NSE or BSE cash equity in today's instrument list. On create, absent means empty; on update, absent keeps the members, present replaces them (members kept from before are not checked again).

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
409	watchlist_name_taken	The caller already has a watchlist with this name.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

PUT

curl -X PUT "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Breakouts (large caps)",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }'

import os

import requests

response = requests.put(
    "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "name": "Breakouts (large caps)",
        "symbols": [
            "CT:EX:RELIANCE-EQ",
            "CT:EX:INFY-EQ",
        ],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>', {
  method: 'PUT',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Breakouts (large caps)",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea6"
  },
  "error": null
}

Delete a watchlist #

DELETE /v1/watchlists/{watchlist_id} app session

Deletes the watchlist, its members and notes.

More about this

Running stock strategies on it stop starting new trades (watchlist_deleted); open trades keep every exit.

Parameters

watchlist_id path · string required

Watchlist id.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

DELETE

curl -X DELETE "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.delete(
    "https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/watchlists/<watchlist_id>', {
  method: 'DELETE',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response: 204, no body.