API Reference

Published Annolyse data, in JSON

Use the public JSON routes to read covered company profiles, latest metrics, historical metric rows, source lineage, market-data snapshots, and cross-company metric tables.

OpenAPI JSON Methodology

https://www.annolyse.ai

Start here

The API is intentionally narrow: it reads the same published coverage used by Annolyse pages, with explicit status codes, rate-limit headers, and documented null handling.

Published data only

The JSON routes expose Annolyse publication data. They do not expose internal working files, private storage paths, or unpublished review states.

No key required

The public routes support browser-side reads with CORS. Treat the service as rate-limited public data rather than a private application backend.

Null is intentional

Unavailable, unsupported, or not meaningful values are returned as null. Do not coerce null into zero in ranking or chart logic.

Quality flags matter

Metric rows can carry caveats such as basis discontinuity, denominator distortion, insufficient history, or non-comparable periods.

JSON routes

These routes require no API key. They are read-only and return published company and metric data.

GET

/api/v1/companies/SCT

Returns a covered company's profile, latest briefing, longitudinal metrics history, and market-data snapshot when available.

companylatestBriefinglatestMetricsmetricsHistorymarketData

GET

/api/v1/metrics/ocf_ebitda_pct

Returns one metric across all covered companies, sorted with available values first.

metricrows[].tickerrows[].sectorLabelrows[].periodrows[].briefingSlugrows[].value

GET

/api/v1/openapi.json

Downloadable OpenAPI 3.1 contract for the public JSON routes.

openapiinfoserverspathscomponents.schemas

Request examples

Use the canonical HTTPS origin. The bare domain and HTTP URLs may redirect before returning data.

curl -L -sS https://www.annolyse.ai/api/v1/openapi.json

curl -L -sS https://www.annolyse.ai/api/v1/companies/SCT

curl -L -sS https://www.annolyse.ai/api/v1/metrics/ocf_ebitda_pct

Integration wrapper

Check both the HTTP status and the ok field so malformed requests, missing coverage, and rate limits fail loudly in your application.

async function annolyseGet(path) {
  const response = await fetch(`https://www.annolyse.ai${path}`, {
    headers: { Accept: "application/json" },
  });
  const data = await response.json();

  if (!response.ok || data.ok === false) {
    throw new Error(data.error ?? `Annolyse API error ${response.status}`);
  }

  return data;
}

const company = await annolyseGet("/api/v1/companies/SCT");
const metric = await annolyseGet("/api/v1/metrics/ocf_ebitda_pct");

Response contract

The OpenAPI route is the machine-readable source of truth. These summaries highlight the fields most integrations should care about.

Company response

ok

boolean / required / -

True on success.

company.slug

string / required / -

Lowercase company route slug.

company.ticker

string / required / -

NZX ticker.

company.company

string / required / -

Display company name.

company.sectorLabel

string / nullable / -

Readable sector / sub-sector label.

latestBriefing

object / required / -

Most recent published briefing, including title, subtitle, markdown content, and source-document links.

latestMetrics.metrics

object / required / mixed

Latest normalized metric map. Missing or inapplicable values are null.

latestMetrics.metricQualityFlags

object / required / -

Metric-keyed quality flags warning about basis discontinuity, denominator distortion, insufficient history, and other comparability limits.

latestMetrics.historicalAnalyticalContext

object / nullable / -

Legacy internal-shaped historical context retained for compatibility. Prefer the stable top-level historicalContext field for new integrations.

metricsHistory[]

array / required / mixed

Chronological metric entries for the covered published periods.

historicalContext.latest

object / nullable / -

Sanitized historical-context observations for the latest published period.

historicalContext.history[]

array / required / -

Sanitized historical-context observations by published period.

sourceLineage.latest.sourceDocuments[]

array / required / -

Public source documents backing the latest period.

sourceLineage.history[]

array / required / -

Public source-document lineage by published period.

marketData.price

number / nullable / quoted currency

Latest available share price snapshot.

marketData.asOf

string / nullable / ISO date-time

Provider quote timestamp for the latest available share price.

marketData.feedRefreshedAt

string / nullable / ISO date-time

Annolyse market-data feed refresh timestamp.

marketData.marketCapNzdm

number / nullable / NZD millions

Latest available market-cap snapshot.

marketData.priceChange12moPct

number / nullable / %

Share price percentage change over the available 12-month trading window.

marketData.fiftyTwoWeekHigh

number / nullable / quoted currency

Highest daily share price in the available 52-week trading window.

marketData.fiftyTwoWeekLow

number / nullable / quoted currency

Lowest daily share price in the available 52-week trading window.

Metric response

ok

boolean / required / -

True on success.

metric.key

string / required / -

Requested metric key.

metric.label

string / required / -

Human-readable metric label.

metric.format

string / required / -

One of money, percent, ratio, days, or cents.

rows[].ticker

string / required / -

NZX ticker.

rows[].companySlug

string / required / -

Lowercase company route slug.

rows[].sectorLabel

string / nullable / -

Readable sector / sub-sector label.

rows[].period

string / required / -

Latest published reporting period used for the value.

rows[].briefingSlug

string / required / -

Briefing route slug backing the value.

rows[].value

number / nullable / metric.format

Metric value, sorted with available values first.

rows[].qualityFlags[]

array / required / -

Additive metric-quality flags for the requested value; empty when no known quality caveat applies.

rows[].historicalObservation

object / nullable / -

Sanitized preserved historical-context observation for the requested metric, when available.

rows[].sourceDocuments[]

array / required / -

Public source documents backing the row's value.

Status codes

200: Successful response. JSON routes return { ok: true, ...payload }.
400: Malformed ticker or metric key.
404: Ticker, metric key, or embed slug is not covered by the published corpus.
429: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.
500: Unexpected server-side data or storage error. JSON routes return { ok: false, error: ... }.

Headers

Access-Control-Allow-Origin: Public JSON routes are intentionally readable from browser clients.
X-RateLimit-Limit: Maximum requests per one-minute window for company and metric data routes.
X-RateLimit-Remaining: Requests remaining in the current one-minute window.
X-RateLimit-Reset: Seconds until the current one-minute window resets.
Retry-After: Present on 429 responses.

Integration notes

Use the OpenAPI document as the machine-readable contract when generating client types.
Cache company and metric responses in your application when practical. Company payloads can be large because they include published briefing content and metric history.
Retry 429 responses after the number of seconds in the Retry-After header.
Prefer the stable top-level historicalContext field over the legacy latestMetrics.historicalAnalyticalContext shape.
Check marketData.asOf, marketData.stale, marketData.priceKind, and marketData.publicDisplaySuppressionReason before presenting valuation views.

Metric keys

The metric endpoint accepts the keys listed below. Units and display formats are included in the OpenAPI contract.

revenue

money / NZD millions

revenue_growth_pct

percent / %

ebitda

money / NZD millions

ebitda_margin_pct

percent / %

pbt

money / NZD millions

pbt_growth_pct

percent / %

npat

money / NZD millions

npat_growth_pct

percent / %

ocf

money / NZD millions

ocf_ebitda_pct

percent / %

fcf_pre_lease

money / NZD millions

fcf_post_lease

money / NZD millions

dps_cents

cents / cents per share

payout_ratio_npat_pct

percent / %

annual_payout_ratio_eps_pct

percent / %

roe_pct

percent / %

net_debt

money / NZD millions

net_debt_ebitda

ratio / x

debtor_days

days / days

inventory_days

days / days

total_assets

money / NZD millions

Other public surfaces

These are useful for distribution and embeds, but they are not part of the JSON API contract.

GET/feed.xml

RSS feed of newly published briefings.

GET/embed/sct-hy26

Minimal iframe-friendly briefing widget with key metadata and linkback.

async function annolyseGet(path) { const response = await fetch(`https://www.annolyse.ai${path}`, { headers: { Accept: "application/json" }, }); const data = await response.json(); if (!response.ok || data.ok === false) { throw new Error(data.error ?? `Annolyse API error ${response.status}`); } return data; } const company = await annolyseGet("/api/v1/companies/SCT"); const metric = await annolyseGet("/api/v1/metrics/ocf_ebitda_pct");

Status codes

200

Successful response. JSON routes return { ok: true, ...payload }.

400

Malformed ticker or metric key.

404

Ticker, metric key, or embed slug is not covered by the published corpus.

429

Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

500

Unexpected server-side data or storage error. JSON routes return { ok: false, error: ... }.

Headers

Access-Control-Allow-Origin

Public JSON routes are intentionally readable from browser clients.

X-RateLimit-Limit

Maximum requests per one-minute window for company and metric data routes.

X-RateLimit-Remaining

Requests remaining in the current one-minute window.

X-RateLimit-Reset

Seconds until the current one-minute window resets.

Retry-After

Present on 429 responses.

Integration notes

Use the OpenAPI document as the machine-readable contract when generating client types.

Cache company and metric responses in your application when practical. Company payloads can be large because they include published briefing content and metric history.

Retry 429 responses after the number of seconds in the Retry-After header.

Prefer the stable top-level historicalContext field over the legacy latestMetrics.historicalAnalyticalContext shape.

Check marketData.asOf, marketData.stale, marketData.priceKind, and marketData.publicDisplaySuppressionReason before presenting valuation views.