Managing your symbols

Managing Symbols

How symbol lists are organized

your membership or tier plan carries one symbol list that all of its edge products and datasets inherit automatically. Edge products do not have separate lists; setting the list on the membership applies to every edge product under it.

Custom lists, default lists, and your plan limit

Each list resolves in this order:

  1. A custom list you have set for the product (or its membership owner), if any.
  2. Otherwise, the default list for your plan's tier.

Either way, the effective (enforced) list is capped to your plan's symbol limit. If your stored custom list is larger than your current limit — for example after a downgrade — the extra symbols stay saved but are inactive: the API caps what it returns and enforces, and reports truncated: true along with storedCount (how many you have saved) so you can see the difference. Those symbols become active again if your limit increases.

Managing your symbols in the console

The My Universe section lets you view and edit each product's symbol list from your browser.

To edit a list:

  1. Open My Universe and choose the product whose universe you want to manage.
  2. If you're still using your plan's default list, click Copy to customize to start your own editable copy. (This is free, and it stops your list from auto-updating with the default going forward.)
  3. Add symbols by typing into the add box and pressing Enter (or clicking Add). You can add one symbol or several at once — separate them with commas or spaces, e.g. AAPL, MSFT, NVDA. Newly added symbols appear highlighted until you save.
  4. Remove a symbol with the ✕ on its chip. Removed symbols stay visible, struck-through, until you save.
  5. Click Save changes to apply. A summary shows exactly what you added and removed before you commit.

How editing works

  • Adding is always free. Add symbols any time, as often as you like, up to your plan's symbol limit.
  • Removing or replacing uses your weekly change. Any save that removes a symbol counts as your one change per week. It resets every Monday at 00:00 UTC. Once you've used it, you can still add symbols, but you can't remove or replace again until the reset — the console shows you the exact date it unlocks and asks you to confirm before you spend it.
  • New subscriptions get a grace period. For your first 2 days, every edit is free — add and remove freely while you build your initial list.
  • Changing your plan. Upgrading immediately restores your weekly change. Downgrading trims your list to the new (smaller) limit — the extra symbols stay saved but become inactive — and resets your weekly change so you can re-curate right away.
  • At your limit. When your list is full, the add box is disabled until you remove a symbol, or upgrade your plan for more room.

View-only cases

Some products can be viewed but not edited in the console:

  • The Free plan (free trial) — while you're on the free plan you can view a product's symbol universe, but customizing it requires a paid plan. Upgrade to start editing.
  • Edge products — these inherit their symbol list from your membership; edit the membership to change what they see.
  • Unlimited plans — already include every available symbol, so there's nothing to customize.

Prefer automation? Everything here is also available through the API and the MCP server (below), and the same rules apply to all three.

Manage Symbol Permissions API Documentation

This API lets you retrieve, add, remove, and replace the custom symbols for each of your products. There are two ways to address a list:

  • Product-scoped endpoints (recommended) — /symbols/product/{productId}/... target a specific product's list. Naming an edge product automatically resolves to the membership list it inherits.
  • Dataset-scoped endpoints — /symbols/dataset/{datasetId}/... are equivalent but let you address a list by a dataset you know rather than a product id.
  • Org-wide endpoints — /symbols/current and /symbols/custom are a convenience that operate on your membership list (or your org-level list if you have no membership).

Start with GET /symbols/scopes to discover the products and lists available to your account.

Authentication

All endpoints require a token query parameter for authentication. Endpoints that modify symbols (POST, PUT, DELETE) require a secret token (sk_...); public tokens (pk_...) are read-only.

Operation Limits

Editing is governed by the same rules everywhere — the API, the MCP server, and the console:

  • Adding symbols is always free (PUT, or a POST that only adds). You can add any time, up to your plan's symbol limit.
  • Removing or replacing symbols uses your one change per week. Any DELETE, or any POST that drops a symbol, counts as a change. It resets every Monday at 00:00 UTC. If you've already used this week's change, the request returns 403 with reason: "weekly_limit" and a nextResetAt timestamp (epoch ms) telling you when it unlocks.
  • New subscriptions get a 2-day grace period from the subscription date, during which all edits — including removals and replacements — are free and don't count against your weekly change.
  • Plan changes are handled automatically: upgrading restores your weekly change immediately; downgrading trims your saved list to the new limit (extra symbols stay saved but inactive) and restores your weekly change so you can re-curate.
  • Free trials are view-only. You can read a list, but any write returns 403 with reason: "trial_read_only". Upgrade to a paid plan to customize.

The GET .../current response includes canRotate (whether a removal/replacement is available now), nextResetAt (when your weekly change unlocks), and inGrace/graceEndsAt so you can check before you write.

Discover your lists

List Symbol Scopes

GET /symbols/scopes?token={token}

Returns every symbol list you can manage. scopes are the lists you own (your membership and any standalone products), each with the edge products that inherit it (inheritedBy). products maps every subscribed product (including edge products) to the list that applies to it (ownerProductId). defaultProductId is the product the org-wide endpoints act on.

Response:

{
  "success": true,
  "defaultProductId": 10,
  "scopes": [
    {
      "productId": 10,
      "slug": "pro-membership",
      "type": "tiered",
      "isMembership": true,
      "isDefault": true,
      "symbolAccess": { "list": "dow30", "count": 30 },
      "inheritedBy": [{ "productId": 20, "slug": "real-time-news" }]
    },
    {
      "productId": 30,
      "slug": "fundamentals",
      "type": "standalone",
      "isMembership": false,
      "isDefault": false,
      "symbolAccess": { "list": "sp500", "count": 100 },
      "inheritedBy": []
    }
  ],
  "products": [
    { "productId": 10, "slug": "pro-membership", "type": "tiered", "ownerProductId": 10 },
    { "productId": 20, "slug": "real-time-news", "type": "edge", "ownerProductId": 10 },
    { "productId": 30, "slug": "fundamentals", "type": "standalone", "ownerProductId": 30 }
  ]
}

Product-scoped endpoints

Get Current Symbols (a product's effective list)

GET /symbols/product/{productId}/current?token={token}

Returns the effective list for a product: what a data request is actually validated against, capped to your plan limit. If you have no custom list, this returns your tier's default list.

Response:

{
  "success": true,
  "symbols": ["AAPL", "MSFT", "GOOGL"],
  "count": 3,
  "list": "sp500",
  "limit": 100,
  "used": 3,
  "isUnlimited": false,
  "isDefault": false,
  "source": "custom",
  "storedCount": 3,
  "truncated": false,
  "inGrace": false,
  "graceEndsAt": null,
  "canRotate": true,
  "nextResetAt": 1789000000000,
  "productId": 30,
  "ownerProductId": 30,
  "ownerType": "own",
  "inheritedFromEdge": false
}

Editing-status fields: used (symbols in your saved custom list), isDefault (true when you haven't customized yet), canRotate (whether a removal/replacement is available now), nextResetAt (epoch ms when your weekly change next unlocks), and inGrace/graceEndsAt (your new-subscription grace window). A free trial additionally returns readOnly: true (with canRotate: false) — you can read the list but not change it.

For an edge product, the request resolves to the membership list — note ownerType and inheritedFromEdge:

{
  "success": true,
  "symbols": ["AAPL", "MSFT"],
  "count": 2,
  "list": "dow30",
  "limit": 30,
  "isUnlimited": false,
  "productId": 20,
  "ownerProductId": 10,
  "ownerType": "membership",
  "inheritedFromEdge": true
}

For an unlimited plan:

{
  "success": true,
  "symbols": null,
  "count": 0,
  "list": "unlimited",
  "limit": 0,
  "isUnlimited": true
}

When your saved list exceeds your current limit (for example after a downgrade), the response is capped and reports the difference:

{
  "success": true,
  "symbols": ["AAPL", "MSFT"],
  "count": 2,
  "limit": 2,
  "storedCount": 5,
  "truncated": true,
  "productId": 30,
  "ownerProductId": 30,
  "ownerType": "own"
}

Get Custom Symbols (a product's saved list, uncapped)

GET /symbols/product/{productId}/custom?token={token}

Returns the full custom list you have saved for the product — not capped to your plan limit — so you can review everything you have stored. It still reports truncated/storedCount/limit so you can see how much is currently active.

Response:

{
  "success": true,
  "symbols": ["AAPL", "MSFT", "GOOGL", "AMZN", "META"],
  "count": 5,
  "list": "sp500",
  "limit": 3,
  "storedCount": 5,
  "truncated": true,
  "productId": 30,
  "ownerProductId": 30,
  "ownerType": "own",
  "inheritedFromEdge": false
}

Set Custom Symbols (replace the list)

POST /symbols/product/{productId}/custom?token={token}

Replaces the entire custom list for the product. Subject to the operation limits above and requires a secret token. Targeting an edge product writes to the membership list it inherits; the response reports where the write landed.

Request Body:

{
  "symbols": ["AAPL", "MSFT", "GOOGL"]
}

Response:

{
  "success": true,
  "message": "Custom symbols updated successfully",
  "symbols": ["AAPL", "MSFT", "GOOGL"],
  "ownerProductId": 30,
  "ownerType": "own",
  "inheritedFromEdge": false
}

Add Custom Symbols

PUT /symbols/product/{productId}/custom?token={token}

Adds symbols to the product's custom list, keeping existing ones. You can add at any time until you reach your plan limit. Requires a secret token.

Request Body:

{
  "symbols": ["AAPL"]
}

Response:

{
  "success": true,
  "message": "Custom symbols added successfully",
  "symbols": ["MSFT", "GOOGL", "AAPL"],
  "ownerProductId": 30,
  "ownerType": "own",
  "inheritedFromEdge": false
}

Remove Custom Symbols

DELETE /symbols/product/{productId}/custom?token={token}

Removes the specified symbols from the product's custom list. Subject to the operation limits above and requires a secret token.

Request Body:

{
  "symbols": ["AAPL"]
}

Response:

{
  "success": true,
  "message": "Custom symbols removed successfully",
  "symbols": ["MSFT", "GOOGL"],
  "ownerProductId": 30,
  "ownerType": "own",
  "inheritedFromEdge": false
}

Dataset-scoped endpoints

The same four operations are available addressed by dataset id instead of product id. They behave identically, resolving to the list that governs that dataset (the membership list for edge datasets):

GET    /symbols/dataset/{datasetId}/current?token={token}
GET    /symbols/dataset/{datasetId}/custom?token={token}
POST   /symbols/dataset/{datasetId}/custom?token={token}
PUT    /symbols/dataset/{datasetId}/custom?token={token}
DELETE /symbols/dataset/{datasetId}/custom?token={token}

Org-wide endpoints (convenience)

GET/POST/PUT/DELETE /symbols/current and /symbols/custom operate on your membership list (or your org-level list if you have no membership). They are kept for backward compatibility; use the product-scoped endpoints when you have more than one list.

Response (GET /symbols/current) — the same shape as the product-scoped current, resolved against your membership list:

{
  "success": true,
  "symbols": ["AAPL", "MSFT", "GOOGL"],
  "count": 3,
  "list": "dow30",
  "limit": 100,
  "used": 3,
  "isDefault": false,
  "source": "custom",
  "storedCount": 3,
  "truncated": false,
  "canRotate": true,
  "nextResetAt": 1789000000000,
  "ownerProductId": 10,
  "ownerType": "membership"
}

Managing symbols through the MCP server

If you connect through the MCP server, the same capabilities are exposed as tools:

  • list_symbol_scopes — discover the lists you can manage (mirrors GET /symbols/scopes).
  • get_symbol_universe — view a list's effective symbols, limit, and truncation info.
  • set_symbol_universe / add_symbols_to_universe / remove_symbols_from_universe — manage a list.

Each tool takes an optional product argument (a product name/slug or id). Omit it to use your default list (your membership, or your only product); if your account has several standalone products, the tool asks you to specify one. Naming an edge product edits the shared membership list it inherits, and the tool's response explains the inheritance.

Error Responses

All endpoints may return the following error response:

{
  "success": false,
  "message": "Error message describing the issue"
}

Common cases:

  • Not subscribed — a request for a product or dataset you don't have returns HTTP 403.
  • Weekly change already used — a removal/replacement when you've spent this week's change returns HTTP 403 with a machine-readable reason and the reset time: 
    {
  "success": false,
  "reason": "weekly_limit",
  "nextResetAt": 1789000000000,
  "message": "This change removes symbols, which uses your weekly change — already spent this week."
}
  • Free plan / trial (view-only) — any write on a free-plan (trial) account returns HTTP 403: 
    {
  "success": false,
  "reason": "trial_read_only",
  "message": "Your free trial can view the symbol universe but can't change it. Upgrade your plan to customize."
}
  • Over the limit — an add or replace that would exceed your plan's symbol limit returns HTTP 400.

Notes

  • Symbols must be uppercase, 1–20 characters, and made up of letters and numbers plus the separators . _ - / (for example AAPL, BRK.B, AAPL.O). This covers tickers, RICs, ISINs, FIGIs, CUSIPs, and LEIs.
  • A single request accepts at most 10,000 symbols; larger arrays are rejected with HTTP 400. (Your effective list is still capped to your plan's symbol limit — this is just a request-size bound.)
  • Adding symbols is free any time, up to your plan limit. Removing or replacing uses your one change per week, which resets every Monday (00:00 UTC). New subscriptions get 2 days of free editing to start.
  • Each product's number of allowed custom symbols depends on its subscribed plan.
  • Edge products always inherit their membership's list and cannot be set separately.
  • Unlimited plans have no symbol restrictions.
  • Operations that modify symbols (POST, PUT, DELETE) require a secret token.
  • Changes to your symbol access may take up to 5 minutes to reflect in the system.
  • The Free plan (free trial) is view-only — you can see your symbol universe but need a paid plan to customize it.