Prerequisites
Every call needs a Bearer token. See Authentication for
how to get one. The REST API base URL is
https://api.noonum.ai/v1. The MCP server URL is
https://mcp.noonum.ai/mcp.The lifecycle at a glance
1
Write a good objective
The objective determines which companies get selected and how their relevance is scored.You author the objective yourself and submit it with
POST /strategies (Step 3). Two
helper endpoints can refine a draft first: POST /enhance-objective sharpens it and
POST /reverse-objective flips it. Both are covered below.Format
Always begin with “The strategy is to invest in companies that are …” followed by a single paragraph describing the opportunities, products, themes, and value-chain segments you want exposure to.A strong objective is:- Specific: “…developing solid-state battery technology for electric vehicles”, not “…in the energy sector”.
- Scoped to a clear value-chain segment, such as upstream suppliers, manufacturers, or end-market applications.
- Theme-focused: describe the investment theme, not individual companies.
- Product-oriented: focus on what companies do, build, or sell.
- Naming specific companies. Noonum finds them for you.
- Generic sector labels with no thematic direction.
- Overly broad framing that would match thousands of companies.
- Negative framing. Use exclusions for what you want to leave out.
Examples
Sharpening a rough thesis
If you start from a rough idea, expand it into a structured objective: keep the original intent and scope, then add value-chain segments and specificity around products, technologies, or business models.POST /enhance-objective does this for you: send a draft
as { "objective": ... } and it returns an enhancedObjective plus an
improvementsSummary describing what changed.From an article
To build from a news article, report, or post, pass the relevant text straight toPOST /enhance-objective. Paste in an article you have, or fetch a page and pass its text.
The endpoint reads the raw text and returns a focused enhancedObjective. A source with no
identifiable investment theme is a poor one.Reverse objectives
To create a thematic inverse (useful for hedging or pair trades), flip the directional exposure while keeping positive framing. Describe what the opposite side is rather than negating the original:POST /reverse-objective automates this: send the original as { "objective": ... } and it
returns a reverseObjective and a suggested reverseName.Pick a name
Choose a descriptive name of 2–5 words with no “Strategy” suffix, for example “AI Infrastructure”, “GLP-1 Weight Loss”, or “Nuclear Renaissance”.2
Check what already exists
Check whether the strategy already exists. Noonum maintains a curated library of premade
strategies, and you may already have a similar strategy of your own.Compare your objective against the names and objectives that come back. If a close match
exists, reuse it as-is, copy it under a new name and objective, or proceed with a new
strategy. Both calls are read-only, so listing alone is enough if you just want to browse.
3
Create the strategy
Create the strategy with your confirmed name and objective. Exclusions are optional here and
can be added later once you’ve seen the holdings.The response includes the new strategy’s
id, which you use to submit and to retrieve
results.4
Submit for processing
Creating a strategy stores its definition. Submitting runs the pipeline that finds and
ranks companies, a job that can take several minutes.
Submit and poll
The submit call returns the strategy with astatus field. status is the run’s progress as
a percentage, from 0 to 100. Poll GET /strategies/{strategyId} until status reaches
100. At that point completed is true, and you can fetch results with the read-only
endpoints below. A status of -1 means an error: either a temporary one that Noonum
retries automatically, or a failed run.Practical notes:- The submit call returns at once. The run itself can take several minutes, so poll as above instead of raising your HTTP timeout.
- Each submit starts a new run, which uses one credit from your plan. A failed run is not charged.
- If your plan has no credits left for the current period, the REST API rejects the submit
with
429. - If the strategy is already processing, the REST API rejects the submit with
423. Wait for the in-flight run to finish or fail.
submit_strategy also returns at once, with the submitted version and
its run state. Poll get_strategy_version until completed is true. A status of -1 is
a temporary error that Noonum retries automatically, and -2 means the run failed. See
Runs in the MCP server reference.5
Review the holdings
Once Review the inclusion reasoning for the top 5–10 companies to judge whether the objective
landed where you intended. If the companies aren’t what you expected, adjust the objective
(make it more specific, better-scoped, or target a different value-chain segment) rather
than reaching for exclusions.
status reaches 100, retrieve the strategy’s ranked companies. Each row carries
scoring and exposure metrics. Set includeReasoning=true to see why each company was
included.Filtering
The list comes back highestconvictionScore first. By default, the REST API applies the
strategy’s saved filter_intent. If you pass any of these query parameters, the REST API
ignores the saved filter for that request, so pass every filter you want:exchangeRegion: region labels such asEurope, or ISO 10383 exchange codes (MICs) such asXNAS. They pick which listing represents each company. 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 runs carry 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 parameters, so sort on other fields in your own code.convictionScore, linguisticBeta, and marketBuzz are Noonum’s thematic signals.
convictionScore and linguisticBeta run from 0 to 1. See
Signals and scores for what each measures.The MCP server’s get_strategy_companies tool takes the same filters. To get the full list
with no filter, pass exchangeRegion as []. The tool returns one page at a time. You
choose the page with limit (1 to 100, default 50) and offset. With includeReasoning,
keep limit at 20 or less. See Filters and metrics in the MCP
server reference.The REST API returns the holdings as JSON only. To export them as CSV, write the rows to a
CSV file in your own code. Over the MCP server, page through get_strategy_companies to
collect the full list.Empty results
If a strategy comes back with no companies, the theme is probably too niche. Broaden the objective, or start from a related premade strategy.6
Refine with exclusions
Exclusions are short phrases describing types of company to filter out. Base them on the
companies you see in the holdings, after the run, not on blind theme-based guesses.Write each exclusion as a description of what a company is, not what it isn’t:Apply exclusions by updating the strategy, then resubmitting so the pipeline re-ranks with
the new filter:Then re-review the holdings (Step 5) to confirm the right companies were removed and the
ones you wanted to keep remain.
- 2–6 words per phrase.
- Do not prefix with “exclude” or use negation.
- Describe the company type directly.
Where to go next
- Dig into per-company evidence with
GET /strategies/{strategyId}/companies/{companyId}(get_strategy_company) or pull all reasoning at once withGET /strategies/{strategyId}/evidences(REST API only). - Pull historical snapshots of a strategy’s holdings to study how the theme evolved.
- Build and review strategies from an LLM client with the Noonum MCP server.