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 archiving.
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).
To browse the public catalog of completed, non-archived strategies, pass scope=public to GET /strategies. Use scope=all to return your own strategies plus the catalog, deduplicated.

Endpoint quick reference

All REST paths are relative to https://api.noonum.ai/v2. The MCP server exposes most of them as named tools. The REST API returns the full list of strategies or holdings in one response. Over the MCP server, list_strategies and get_strategy_companies return one page at a time. Page through with limit and offset, and read total for the count across all pages.
  • list_strategies takes a limit of 1 to 50 (default 20). Each entry has the strategy’s id, name, objective, public, status, completed, and summary performance metrics. Call get_strategy for the rest. It leaves out the weekly performance series.
  • get_strategy_companies takes a limit of 1 to 100 (default 50). With includeReasoning, keep the limit at 20 or less, because each row gets much larger.

View holdings

Fetch a strategy’s companies with GET /strategies/{strategyId}/companies. The endpoint returns a JSON array, highest convictionScore first. It reads the active version’s latest completed run by default. Pass asOfDate, versionId, or both to select a different run. 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 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. A run that carries no market cap ignores the bounds.
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. Build a strategy covers the same parameters.
scoringMinMarketCap is deprecated. The REST API accepts it and ignores it. To leave out smaller companies, set marketCapMin.

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 included company. 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, get_strategy_companies returns one page at a time, so raise offset page by page until you have all total companies.

Get a factsheet

The factsheet is generated on demand. Request it with POST /strategies/{strategyId}/factsheet, then read it with GET /strategies/{strategyId}/factsheet:
  • When the PDF is ready, the GET returns 302 Found with a download URL in the Location header. The URL expires after about 5 minutes.
  • Otherwise the GET returns 200 OK with a FactsheetStatus body. Its status is generating while a generation is in flight, not_requested when none has been requested, or unavailable when the run cannot have one.
Only the strategy’s owner can request a factsheet. For anyone else, the POST returns 404. Only the first request starts a generation, so asking again while the factsheet is generating starts nothing new. Set force to true in the POST body to regenerate an existing factsheet. If a generation does not finish, the status goes back to not_requested and you can request it again. Live and historical runs can both have a factsheet. A POST for a date whose run has not finished returns 409. To target a specific run, pass asOfDate and versionId as query parameters on the GET, or as_of_date and version_id in the POST body. Both default to the active version’s latest completed run. Request a factsheet after refinement to capture the updated state.
When polling, disable redirect following so you can tell a 302 (ready) from a 200 (still generating).
Through the MCP server, request_strategy_factsheet requests the factsheet and get_strategy_factsheet reads it. get_strategy_factsheet returns a status of ready, generating, not_requested, or unavailable. When the status is ready, the result also has a url that expires after about 5 minutes. Call the tool again for a fresh one.

Archive a strategy

DELETE /strategies/{strategyId} archives the strategy rather than destroying it: it returns 204, is hidden from reads, and is scheduled for permanent deletion after a 30-day grace window.
  • List archived strategies still inside the window with GET /strategies/archived. Each carries archived_at and permanent_delete_at.
  • Restore one with POST /strategies/{strategyId}/revive. This returns the revived strategy with archived_at and permanent_delete_at reset to null.
Once the grace window has elapsed, Noonum permanently deletes the strategy and POST /strategies/{strategyId}/revive returns 410 Gone. Revive before then if you need it back.

Status codes

The strategy’s top-level status is a discrete code for the active version’s latest run, live or historical, not a raw percentage: A live run still in progress 30 minutes after you submitted it also reads as -2. Submit again for that date to run it again. status is run-scoped: it reflects the active version’s latest run. completed is true once the active version has a completed run, and it stays true while a newer run is in progress or after one fails. For per-version or per-date detail, read GET /strategies/{strategyId}/versions/{versionId}, or GET /strategies/{strategyId}/runs for every date of a version.

Error handling

  • Strategy not found: list your strategies to confirm the ID. An archived strategy is reachable only via GET /strategies/archived and POST /strategies/{strategyId}/revive.
  • Holdings return 404: the strategy has no completed run yet. Check GET /strategies/{strategyId}. If completed is false, wait for the run to finish.
  • Holdings come back empty: the run finished, but no company qualified or the filter left none. Pass exchangeRegion= to read the list without a filter.
  • Submit returns 423: a run for this version and date is already in progress. Wait for it to finish before you submit again.
  • Submit returns 429: your plan has no credits left in the current period. Each new run uses one credit, and a failed run is not charged. GET /usage (MCP server: get_usage) shows when they refill in refills_at.
  • Submit returns 409: the email you signed in with already belongs to another Noonum account. This can happen when you first signed up with a different sign-in method. Sign in the way you first signed up, or contact support.
  • A request returns 400: a strategy ID, version ID, or date in the request is malformed. IDs are UUIDs, and dates use YYYY-MM-DD. The error message names the bad value.