End-to-end REST integration - Noonum Developers

This tutorial runs the full Noonum workflow from the REST API. It assumes you’ve done Build a strategy, so you know what an objective, a strategy build, and conviction-ranked holdings are. It adds the parts that guide doesn’t cover: optimizing holdings into a weighted portfolio and backtesting that portfolio against a market benchmark. Each step gives you a curl command and the equivalent Python snippet using the requests library.

What you’ll build

Authenticate and smoke-test the connection.
Browse premade strategies and your own strategies.
Look up companies by ticker.
Create a strategy from an objective, submit it, and poll until it’s ready.
Fetch the strategy’s companies and a constructed portfolio with weights.
Backtest those holdings against a benchmark (e.g. SPY).

The submit-then-poll loop and the optimize retry are the two spots where you wait on async work:

Prerequisites

Requirement	Value
REST base URL	`https://api.noonum.ai/v1`
Auth header	`Authorization: Bearer <token>`
`<token>`	Your Noonum API key
Tools	`curl` for the shell examples; Python 3.9+ with `requests` for the code

The <token> is your Noonum API key. See Authentication for how to obtain and send it. Install the Python dependency if you plan to follow the code snippets:

pip install requests

Authenticate and smoke-test

Confirm the service is reachable and your token works.Hit the unauthenticated health check to verify connectivity:

curl -X GET "https://api.noonum.ai/v1/health"

A 200 OK with {"status":"OK","message":"Service is running"} means the API is up.Now make your first authenticated call. Listing your strategies validates the token: it returns 200 (even if the list is empty) when the token is good, and 401 Unauthorized when it isn’t. Replace YOUR_API_KEY with your key:

curl -X GET "https://api.noonum.ai/v1/strategies" \
  -H "Authorization: Bearer YOUR_API_KEY"

The equivalent set-up in Python. Every later snippet reuses this BASE_URL and headers:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.noonum.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.get(f"{BASE_URL}/strategies", headers=headers)
resp.raise_for_status()  # raises on 401/4xx/5xx
print(f"Authenticated. You own {len(resp.json())} strategies.")

One token, two transports The same Bearer token works against the MCP server at https://api.noonum.ai/v1/mcp (HTTP transport). To drive Noonum from an AI agent, you won’t need new credentials. See the MCP overview.

Explore the catalog

Noonum ships a library of read-only premade strategies. Inspect them to see the data shape before you build your own. List them:

curl -X GET "https://api.noonum.ai/v1/premade-strategies" \
  -H "Authorization: Bearer YOUR_API_KEY"

premade = requests.get(f"{BASE_URL}/premade-strategies", headers=headers)
premade.raise_for_status()

catalog = premade.json()
premade_id = catalog[0]["id"]  # a premade strategy id; reused later
for s in catalog[:5]:
    print(s["id"], "-", s["name"])

Each item is a Strategy object with an id, name, objective, and status. Fetch the companies inside any premade strategy with GET /premade-strategies/{strategyId}/companies, the way you will for your own strategies in Step 5. Premade strategies also expose read-only per-company evidence and historical snapshots, covered in Working with premade strategies below.To find the closest existing premade strategy for a plain-English objective, use semantic search:

curl -X POST "https://api.noonum.ai/v1/premade-strategies/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective": "companies that benefit from electric vehicle adoption"}'

The response is a matches array ordered by descending similarity, each wrapping a full Strategy.

Look up companies by ticker

Most Noonum endpoints identify companies by a UUID, not a ticker. Resolve a ticker, name, ISIN, or FIGI fragment to a company id with the helper search endpoint:

curl -X POST "https://api.noonum.ai/v1/helper/companies/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "TSLA"}'

lookup = requests.post(
    f"{BASE_URL}/helper/companies/search",
    json={"query": "TSLA"},
    headers=headers,
)
lookup.raise_for_status()

match = lookup.json()["results"][0]
company_id = match["id"]
print("Resolved:", match["name"], "->", company_id)

Results are ranked with exact matches first, then prefix matches, capped at the top 10. Each result lists its active securities (primary listing first). Any endpoint that takes a company id, including the backtest later in this tutorial, can use an id resolved here.

Create and build a strategy

This is the create → submit → poll loop from Build a strategy, in code: create the strategy (synchronous), submit to start the async theme analysis, then poll until it’s done.

4a. Create

POST /strategies requires a name and an objective; exclusions is optional.

curl -X POST "https://api.noonum.ai/v1/strategies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electric Vehicles",
    "objective": "Identify companies focused on EV manufacturing, battery technology, and charging-station infrastructure."
  }'

create = requests.post(
    f"{BASE_URL}/strategies",
    json={
        "name": "Electric Vehicles",
        "objective": (
            "Identify companies focused on EV manufacturing, battery technology, "
            "and charging-station infrastructure."
        ),
    },
    headers=headers,
)
create.raise_for_status()

strategy = create.json()
strategy_id = strategy["id"]
print("Created strategy:", strategy_id)

A 201 Created returns the new Strategy object. Save its id.

4b. Submit for processing

Submitting kicks off the async build:

curl -X POST "https://api.noonum.ai/v1/strategies/STRATEGY_ID/submit" \
  -H "Authorization: Bearer YOUR_API_KEY"

submit = requests.post(f"{BASE_URL}/strategies/{strategy_id}/submit", headers=headers)
submit.raise_for_status()

A 423 Locked here means a previous submission of the same strategy is still running. Wait for it to finish before resubmitting.

4c. Poll until complete

Poll GET /strategies/{strategyId} and watch status, the percent-complete field; 100 means the build has finished.

from time import sleep

while True:
    poll = requests.get(f"{BASE_URL}/strategies/{strategy_id}", headers=headers)
    poll.raise_for_status()

    status = poll.json()["status"]
    print("status:", status)
    if status == 100:
        break
    sleep(10)

print("Strategy build complete.")

Add exclusions to refine results To drop part of a result, add natural-language exclusions with PATCH /strategies/{strategyId}, then resubmit. The Iterate a strategy guide covers this loop in depth.

Fetch holdings

With the strategy built, retrieve its companies. Pass includeReasoning=true to also get the human-readable explanation for each inclusion.

curl -X GET "https://api.noonum.ai/v1/strategies/STRATEGY_ID/companies?includeReasoning=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

companies = requests.get(
    f"{BASE_URL}/strategies/{strategy_id}/companies",
    params={"includeReasoning": "true"},
    headers=headers,
)
companies.raise_for_status()

holdings = companies.json()
print(f"{len(holdings)} companies in the strategy.")
for c in holdings[:5]:
    print(f"  {c['symbol']:6} {c['name']:30} conviction={c.get('convictionScore')}")

Each entry is a Company with id, symbol, name, sector, marketCap, linguisticBeta, marketBuzz, and a convictionScore in (0, 1). The convictionScore is the default ranking metric, an overall thematic-strength score independent of company size. See Signals and scores for what each field means.

Turn the list into a weighted portfolio

The raw company list is unweighted. To get an investable portfolio with per-holding weights, use the construction endpoint. POST /strategies/{strategyId}/optimize tilts the weights by a signal score (default convictionScore):

curl -X POST "https://api.noonum.ai/v1/strategies/STRATEGY_ID/optimize?signalType=convictionScore&maxWeight=0.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

optimize = requests.post(
    f"{BASE_URL}/strategies/{strategy_id}/optimize",
    params={"signalType": "convictionScore", "maxWeight": 0.2},
    headers=headers,
)
optimize.raise_for_status()

result = optimize.json()
weighted = result["portfolio"]
print("Constructed", result["metadata"]["numberStocks"], "holdings")
for c in weighted[:5]:
    print(f"  {c['symbol']:6} weight={c['weight']:.4f}")

The response carries a metadata block (number of holdings, weighted signal score, and expected return/volatility/Sharpe stats) plus a portfolio array where every company also has a weight. A 202 Accepted here means the strategy framework hasn’t finished yet. Keep polling Step 4c.

Backtest the holdings

Validate the portfolio against history. POST /backtest takes a list of holdings (each a companyId + weight), resolves each to a tradeable security, and computes a buy-and-hold NAV with risk statistics versus a benchmark.Build the request from the constructed portfolio you fetched:

backtest_holdings = [
    {"companyId": c["id"], "weight": c["weight"]} for c in weighted
]

backtest = requests.post(
    f"{BASE_URL}/backtest",
    json={
        "holdings": backtest_holdings,
        "years": 5,
        "benchmark": "SPY",
    },
    headers=headers,
)
backtest.raise_for_status()

stats = backtest.json()["metadata"]
bench = backtest.json()["benchmarkMetadata"]
print(f"Portfolio CAGR: {stats['annualizedReturn']:.2%}  Sharpe: {stats['sharpeRatio']}")
print(f"{bench['symbol']} CAGR:     {bench['annualizedReturn']:.2%}  Sharpe: {bench['sharpeRatio']}")

The same call with curl (using two holdings for brevity):

curl -X POST "https://api.noonum.ai/v1/backtest" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"companyId": "83d88f60-f581-4176-bb5c-e0b463d1d442", "weight": 0.5},
      {"companyId": "0c8b9628-6fce-4d95-a787-5b532172a6ea", "weight": 0.5}
    ],
    "years": 5,
    "benchmark": "SPY"
  }'

The response includes:

metadata: total returns, annualizedReturn (CAGR), variance, sharpeRatio, maxDrawdown, plus stockCount, weekCount, and any warnings.
timeSeries: [timestamp, navValue] pairs rebased to 10,000.
benchmarkMetadata and benchmarkTimeSeries: the same stats for the benchmark, aligned to the portfolio’s dates so you can chart them together.

years accepts 1–20 (default 5) and benchmark accepts any symbol such as SPY or QQQ (default SPY). A 400 Bad Request means there was insufficient price data or no companies could be resolved.

Handling errors

Every endpoint shares the same auth and error conventions:

Status	Meaning	What to do
`401 Unauthorized`	Missing/invalid token, or an inactive account	Recheck the `Authorization` header; revisit Authentication
`400 Bad Request`	Malformed body or invalid identifier (e.g. a non-UUID company id)	Read the `error` field in the JSON body and fix the input
`404 Not Found`	The strategy, company, or portfolio doesn’t exist or isn’t visible to you	Verify the id
`423 Locked`	A previous submit of this strategy is still running	Wait, then resubmit
`202 Accepted`	An async result isn’t ready yet	Poll until `status == 100`, then retry

Error responses use a consistent shape, so you can surface the message directly:

resp = requests.get(f"{BASE_URL}/strategies/{strategy_id}", headers=headers)
if not resp.ok:
    detail = resp.json().get("error", resp.text)
    raise RuntimeError(f"Noonum API {resp.status_code}: {detail}")

Working with premade strategies

Noonum maintains a library of read-only premade strategies that expose more data than your own strategies. Beyond listing them and fetching their companies (Step 2), you can inspect the evidence behind each holding and pull historical snapshots. Every endpoint below lives under the /premade-strategies path and takes a premade strategy id: the premade_id you captured from the catalog in Step 2, not the strategy_id of the strategy you built.

Get evidence for a specific company

This endpoint explains why a company is in the premade strategy: a human-readable reasoning plus supporting summaries (evidence excerpts). It takes the premade_id and a company id from that strategy’s holdings:

holdings_resp = requests.get(
    f"{BASE_URL}/premade-strategies/{premade_id}/companies",
    headers=headers,
)
holdings_resp.raise_for_status()
premade_company_id = holdings_resp.json()[0]["id"]

evidence_resp = requests.get(
    f"{BASE_URL}/premade-strategies/{premade_id}/companies/{premade_company_id}",
    headers=headers,
)
evidence_resp.raise_for_status()

company_evidence = evidence_resp.json()
print("isIncluded:", company_evidence.get("isIncluded"))
print("reasoning:", company_evidence.get("reasoning"))
print("summaries (count):", len(company_evidence.get("summaries", [])))

for s in company_evidence.get("summaries", [])[:3]:
    print(f"  [{s['provider']}] {s['text'][:120]}...")

Each summary includes provider (the source), pubDate (a Unix timestamp), and text (the evidence content).

Get evidence for every company at once

Fetch reasoning and evidence for all companies in the premade strategy in a single call:

all_evidences_resp = requests.get(
    f"{BASE_URL}/premade-strategies/{premade_id}/evidences",
    headers=headers,
)
all_evidences_resp.raise_for_status()

all_evidences = all_evidences_resp.json()["evidences"]
print("Companies with evidences:", len(all_evidences))

List the dates with historical data

Premade strategies keep dated snapshots of their holdings. Check which dates are available before requesting one:

dates_resp = requests.get(
    f"{BASE_URL}/premade-strategies/{premade_id}/historical-data/dates",
    headers=headers,
)
dates_resp.raise_for_status()

available_dates = dates_resp.json()["available_dates"]
print("Available dates:", available_dates)

The response is {"available_dates": ["2024-01-31", "2024-02-29", ...]}. Only dates with completed results appear.

Download the holdings for a historical date

Retrieve the full company list as it stood on a specific date:

date = available_dates[0]
historical_resp = requests.get(
    f"{BASE_URL}/premade-strategies/{premade_id}/historical-data",
    params={"date": date},
    headers=headers,
)
historical_resp.raise_for_status()

companies = historical_resp.json()
print(f"Companies for {date}:", len(companies))

A 409 Conflict means the snapshot for that date is still processing or failed. Pick another date from available_dates.

Next steps

You now have the full loop: authenticate → build → fetch holdings → optimize → backtest. From here:

Refine results with exclusions in the Iterate a strategy guide.
Browse every endpoint, with request/response schemas and an interactive try-it console, in the API Reference.
Drive Noonum from an AI agent with the same token via the MCP overview.

​What you’ll build

​Prerequisites

​4a. Create

​4b. Submit for processing

​4c. Poll until complete

​Turn the list into a weighted portfolio

​Handling errors

​Working with premade strategies

​Get evidence for a specific company

​Get evidence for every company at once

​List the dates with historical data

​Download the holdings for a historical date

​Next steps

What you’ll build

Prerequisites

4a. Create

4b. Submit for processing

4c. Poll until complete

Turn the list into a weighted portfolio

Handling errors

Working with premade strategies

Get evidence for a specific company

Get evidence for every company at once

List the dates with historical data

Download the holdings for a historical date

Next steps