Skip to main content
A Noonum strategy turns an investment thesis into a grounded, ranked list of companies. You write an objective describing the kind of companies you want exposure to, and Noonum scores the companies that fit it, each with reasoning and evidence. Each step below maps to a REST endpoint. Every step after the first also has a matching MCP tool.
Prerequisites Every call needs a Bearer token. See Authentication for how to get one. The REST base URL is https://api.noonum.ai/v2. 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.
Avoid:
  • 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, an improvementsSummary describing what changed, and a suggestedName (see Pick a name).

From an article

To build from a news article, report, or post, pass the relevant text straight to POST /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 reverseName (see Pick a name).

Pick a name

Noonum already suggests a name: suggestedName comes back from POST /enhance-objective, reverseName from POST /reverse-objective. Use either directly, or write your own.If you write your own, 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 publishes a public catalog of strategies, and you may already have a similar strategy of your own.
Pass scope=all to get your own strategies plus the public catalog in one deduplicated list. 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.
Submitting does not generate a factsheet by default, which keeps each run fast while you build and refine. To produce one, pass create_factsheet: true in the submit body. You can also request it afterward with POST /strategies/{strategyId}/factsheet.

Submit and poll

The submit call returns 201 right away with the submitted version’s version_id and its run state. Poll GET /strategies/{strategyId}/versions/{versionId} until status reaches 100, then fetch results with the read-only endpoints below. Other guides refer back to this submit-and-poll loop.status reports progress: 1 through 95 while the run is in progress, and 100 when the strategy is ready. -1 means a temporary error that Noonum retries automatically, so keep polling. -2 means the run failed.Practical notes:
  • A live run usually takes a few minutes and can take up to about 10 minutes.
  • Each run, live or historical, uses one credit from your plan. A failed run is not charged. Once your plan’s credits for the current period are used up, submit returns 429.
  • If the version already has a completed run for the same date, submit uses no credit and returns the version with status 100. Pass force: true to run it again.
  • If a run for the same version and date is already in progress, submit returns 423. Wait for that run to finish or fail.
On the MCP server, submit_strategy also returns right away with the version and its run state. Poll get_strategy_version until completed is true or status is -2. See Runs in the MCP server reference.
5

Review the holdings

Once status reaches 100, retrieve the strategy’s ranked companies. Each row carries scoring and exposure metrics. Ask for reasoning to see why each company was included.
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.

Tuning the results

The companies endpoint takes these query parameters to shape what you get back:
  • includeReasoning=true adds the inclusion reasoning text to each company.
  • exchangeRegion keeps companies with a listing in the regions or exchanges you pass, and shows that listing for each one.
  • domicile keeps companies domiciled in the regions or countries you pass.
  • marketCapMin and marketCapMax keep companies whose market cap, in USD, falls within the bounds. A run that carries no market caps ignores the bounds.
If the strategy has a saved filter_intent, the endpoint applies it by default. Passing any of the filter parameters replaces the saved filter for that request. To read the unfiltered list, pass exchangeRegion= with no value. When a filter applies, Noonum recomputes marketBuzz and convictionScore over the companies that remain.convictionScore, linguisticBeta, and marketBuzz are Noonum’s thematic signals; see Signals and scores for what each measures.The companies endpoint returns JSON only. To export the list as CSV, fetch it and write the rows to a file in your own code.On the MCP server, get_strategy_companies takes the same filters and returns one page at a time. limit sets the page size, from 1 to 100 (default 50), and offset sets how many companies to skip. With includeReasoning, keep limit at 20 or less. To read the unfiltered list, pass exchangeRegion as [].

Empty results

If a strategy comes back with no companies, the theme is probably too niche. Broaden the objective, or start from a related strategy in the public catalog.
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:
  • 2–6 words per phrase.
  • Do not prefix with “exclude” or use negation.
  • Describe the company type directly.
For example, to drop cloud-infrastructure names from the example strategy:
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.

Where to go next

  • Dig into per-company evidence with GET /strategies/{strategyId}/companies/{companyId} (get_strategy_company) or pull all reasoning at once with GET /strategies/{strategyId}/evidences (REST API only).
  • Pull historical snapshots of a strategy’s holdings to study how the theme evolved.
  • Drive the flow from an LLM client through the Noonum MCP server.