To create or submit a strategy, see Build a strategy. To run the full refinement loop, see Iterate on a strategy.
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.
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).
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 tohttps://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 withGET /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 includesid, 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 savedfilter_intent. Pass any of these parameters to replace it for that request:
exchangeRegion: region labels such asEurope, or ISO 10383 exchange codes (MICs) such asXNAS. 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 asUS.marketCapMinandmarketCapMax: inclusive market-cap bounds in USD. Historical results fromGET /strategies/{strategyId}/historical-datacarry no market cap, so these bounds do not apply to them.
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 withincludeReasoning=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.
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.
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, fetchGET /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. CheckGET /strategies/{strategyId}and wait for itsstatusto 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. CheckGET /usageto 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.