Skip to main content
A Noonum thematic strategy is a thematic investment definition: a basket of ranked companies assembled around an objective, with evidence-backed metadata for every holding. Each company’s inclusion is grounded in textual evidence, so you can analyze and report on a strategy from the evidence rather than by guessing. The workflows below run against existing strategies through the REST API or the MCP server: viewing holdings, finding outliers, analyzing composition, comparing two strategies, exporting CSV, pulling a factsheet, and deleting.
To create or submit a strategy, see Build a strategy. To run the full refinement loop, see Iterate on a strategy.
Every request needs an Authorization: Bearer <token> header. See Authentication for tokens and API keys.

The three signals

Each holding carries three scores: conviction, linguistic beta, and market buzz. Signals and scores defines each one, its range, and how to read it. This guide assumes that and focuses on which one to lead with for a given question:
  • Conviction for ranking holdings, summarizing a company, or comparing strategies. It is the default ranking metric and headline number.
  • Linguistic beta when you need to defend why a company belongs in the theme, judge how tightly a cluster ties to the thesis, or flag outliers.
  • Market buzz to see which holdings are currently active in the theme versus historically connected but quiet.
Holdings come back sorted by conviction, highest first.

Resolve a strategy

Most operations take a strategy ID. To find one:
  • List your strategies with GET /strategies (MCP server: list_strategies).
  • Fetch a specific strategy with GET /strategies/{strategyId} (MCP server: get_strategy).
Premade strategies are available via GET /premade-strategies (MCP server: list_strategies with scope=public). They are read-only: they cannot be refined or deleted.

Endpoint quick reference

All REST paths are relative to https://api.noonum.ai/v1. The MCP server’s tools call the v2 REST API, so their parameters and responses can differ from the v1 endpoints below. The table lists the closest tool for each task.

View holdings

Fetch a strategy’s companies with GET /strategies/{strategyId}/companies. The endpoint returns the companies from the strategy’s latest completed run as a JSON array, highest convictionScore first. Set includeReasoning=true to fill in each company’s reasoning.

Company fields

Each company includes id, symbol, name, exchange, sector, industry, marketCap, convictionScore, linguisticBeta, and marketBuzz. Its reasoning is null unless you set includeReasoning=true. Use id for per-company queries such as GET /strategies/{strategyId}/companies/{companyId}. You typically won’t surface that ID to end users.

Filter and sort holdings

By default, the list applies the strategy’s saved filter_intent. Pass any of these parameters to replace it for that request:
  • exchangeRegion: region labels such as Europe, or ISO 10383 exchange codes (MICs) such as XNAS. Each company appears with its listing on a matching exchange. Companies with no matching listing are left out.
  • domicile: region labels, or ISO 3166-1 alpha-2 country codes such as US.
  • marketCapMin and marketCapMax: inclusive market-cap bounds in USD. Historical results from GET /strategies/{strategyId}/historical-data carry no market cap, so these bounds do not apply to them.
To get the full list with no filter, pass exchangeRegion= with no value. When a filter applies, the REST API recomputes marketBuzz and convictionScore over the companies that remain. The endpoint has no sort or paging parameters. Sort or filter on any other field, such as sector or linguisticBeta, in your own code. The MCP server’s get_strategy_companies tool takes the same filter parameters, plus limit and offset for paging. See Filters and metrics.

Sparse data

Some companies have incomplete metadata. When a field is missing:
  • Show an em dash (—) in the cell rather than leaving it blank.
  • Keep the company in the table; don’t drop it.
  • Note the count at the bottom (e.g. “N companies with incomplete data”).

Understand why a company is included

GET /strategies/{strategyId}/companies/{companyId} returns one company’s reasoning and supporting evidence. GET /strategies/{strategyId}/evidences returns the same for every company in the strategy. Take the company’s scores from the holdings list and lead with its linguistic beta, then read the evidence. If you only have a name, resolve the company first with POST /helper/companies/search.

Find outliers

Fetch holdings with includeReasoning=true and flag companies that show:
  • Low conviction or low linguistic beta, signaling a tangential connection to the theme.
  • A sector that’s unexpected relative to the thesis.
  • Thin or indirect reasoning.
These are candidates for exclusion. See Iterate on a strategy for how to act on them.

Analyze composition

Profile a strategy from its holdings data:
  • Sector / industry breakdown: a frequency table with average linguistic beta per sector shows which sectors are core to the theme versus peripheral. Watch for any single sector dominating the basket, which can mean the strategy is really a sector bet, and for notable absences.
  • Market-cap distribution: the large-cap, mid-cap, and small-cap mix.
  • Geographic exposure: country distribution.
  • Thematic coherence: the spread of linguistic beta scores tells you whether the strategy is tightly focused or broad.
Signals and scores explains how to interpret each value.

Compare two strategies

Fetch holdings for both strategies, then compute the overlap and differences. A clear layout:

Overlap (N companies, X%)

Unique to Strategy A (N companies)

Unique to Strategy B (N companies)

Summary

  • Overlap: N companies (X% of A, Y% of B).
  • Sector distribution comparison: call out the largest differences.
  • Average conviction comparison. Also note any linguistic beta divergence when thematic coherence is in question.

Export holdings

The REST API returns holdings as JSON only. To export them, fetch GET /strategies/{strategyId}/companies and write the rows to CSV in your own code. Through the MCP server, call get_strategy_companies with limit and offset until you have all total companies, then write them to CSV the same way.

Get a factsheet

GET /strategies/{strategyId}/factsheet redirects (302) to a temporary download URL for a PDF summary of the strategy. The URL is in the Location header. If the strategy has no factsheet, the endpoint returns 404. Use it after refinement to capture the updated state.

Delete a strategy

DELETE /strategies/{strategyId} archives the strategy: it is removed from your account and no longer appears in reads. Premade strategies cannot be deleted. The MCP server’s archive_strategy tool archives a strategy the same way. The v1 REST API cannot restore an archived strategy. For 30 days after archiving, you can restore it with POST /strategies/{strategyId}/revive in the v2 REST API or with the MCP server’s revive_strategy tool. After that, Noonum deletes it permanently.

Error handling

  • Strategy not found: list your strategies to confirm the ID.
  • Holdings return 202: the strategy’s latest run is still in progress. Check GET /strategies/{strategyId} and wait for its status to reach 100.
  • Submit returns 423: a previous run of the strategy is still in progress. Wait for it to finish, then resubmit.
  • Submit returns 429: your plan has no credits left in the current period. Check GET /usage to see when they refill.
  • Submit returns 409: you signed in, and your email already belongs to another Noonum account. Sign in the way you first signed up, or contact support.
  • Premade strategies: read-only; refinement and deletion are rejected.