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).
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 tohttps://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_strategiestakes alimitof 1 to 50 (default 20). Each entry has the strategy’sid,name,objective,public,status,completed, and summaryperformancemetrics. Callget_strategyfor the rest. It leaves out the weekly performance series.get_strategy_companiestakes alimitof 1 to 100 (default 50). WithincludeReasoning, keep thelimitat 20 or less, because each row gets much larger.
View holdings
Fetch a strategy’s companies withGET /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 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 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. A run that carries no market cap ignores the bounds.
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 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, 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 withPOST /strategies/{strategyId}/factsheet, then read it with GET /strategies/{strategyId}/factsheet:
- When the PDF is ready, the
GETreturns302 Foundwith a download URL in theLocationheader. The URL expires after about 5 minutes. - Otherwise the
GETreturns200 OKwith aFactsheetStatusbody. Itsstatusisgeneratingwhile a generation is in flight,not_requestedwhen none has been requested, orunavailablewhen the run cannot have one.
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.
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 carriesarchived_atandpermanent_delete_at. - Restore one with
POST /strategies/{strategyId}/revive. This returns the revived strategy witharchived_atandpermanent_delete_atreset tonull.
Status codes
The strategy’s top-levelstatus 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/archivedandPOST /strategies/{strategyId}/revive. - Holdings return
404: the strategy has no completed run yet. CheckGET /strategies/{strategyId}. Ifcompletedisfalse, 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 inrefills_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 useYYYY-MM-DD. The error message names the bad value.