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:list_strategies). - Fetch a specific strategy with
GET /strategies/{strategyId}(MCP:get_strategy).
GET /premade-strategies (MCP: list_premade_strategies). 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 exposes the same endpoints as named tools.
| Intent | REST endpoint | MCP tool |
|---|---|---|
| List strategies | GET /strategies | list_strategies |
| Get one strategy | GET /strategies/{strategyId} | get_strategy |
| Get holdings | GET /strategies/{strategyId}/companies | get_strategy_companies |
| Look up one company | GET /strategies/{strategyId}/companies/{companyId} | get_strategy_company |
| Search companies | POST /helper/companies/search | search_companies |
| Get evidence | GET /strategies/{strategyId}/evidences | get_strategy_evidences |
| Get factsheet (PDF) | GET /strategies/{strategyId}/factsheet | get_strategy_factsheet |
| Update metadata / exclusions | PATCH /strategies/{strategyId} | update_strategy |
| Reprocess after changes | POST /strategies/{strategyId}/submit | submit_strategy |
| Export holdings as CSV | GET /strategies/{strategyId}/companies (CSV) | download_strategy_companies |
| Delete a strategy | DELETE /strategies/{strategyId} | delete_strategy |
View holdings
Fetch a strategy’s companies withGET /strategies/{strategyId}/companies. The endpoint supports server-side filters, sort_by, sort_order, page, page_size, and include_reasoning parameters. Set include_reasoning=true to add a per-company justification column.
Table columns
The companies endpoint returns these columns:| # | Symbol | Name | Sector | Industry | Market Cap | Conviction | Ling. Beta | Mkt Buzz |
|---|
include_reasoning=true, a Reasoning column is appended. An internal ID column is used 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
filters uses semicolon-separated field:value pairs. String fields match on substrings; numeric fields (marketCap, convictionScore, linguisticBeta, marketBuzz) accept comparison operators. For example, sector:Technology;marketCap:>1B;convictionScore:>0.3 returns large-cap technology holdings with conviction above 0.3. For the full grammar and multi-column sorting, see the MCP server reference.
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
UseGET /strategies/{strategyId}/companies/{companyId} for a single company’s scores, and GET /strategies/{strategyId}/evidences for the underlying evidence. Lead with the linguistic beta score, then read the evidence the API returns. If you only have a name, resolve the company first with POST /helper/companies/search.
Find outliers
Fetch holdings withinclude_reasoning=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%)
| Company | Ticker | Conviction (Strategy A) | Conviction (Strategy B) | Sector |
|---|
Unique to Strategy A (N companies)
| Company | Ticker | Conviction | Sector |
|---|
Unique to Strategy B (N companies)
| Company | Ticker | Conviction | Sector |
|---|
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
Request the companies endpoint in CSV form (MCP:download_strategy_companies) to get all holdings as a CSV string you can save to disk or load into a spreadsheet.
Get a factsheet
GET /strategies/{strategyId}/factsheet returns a presigned URL to a PDF summary of the strategy. 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. Be certain before you call it, and remember that premade strategies cannot be deleted.
Error handling
- Strategy not found: list your strategies to confirm the ID.
- Empty holdings: the strategy may still be processing. Check
GET /strategies/{strategyId}; if its status is below 100%, wait for it to finish. - Update / submit fails: the error message usually means the exclusions need adjustment. Revise and resubmit.
- Premade strategies: read-only; refinement and deletion are rejected.