# NZXplorer — Full API Reference (llms-full.txt)

> Machine-readable API specification for AI agent integration.
> Summary version: /llms.txt | OpenAPI spec: /openapi.json
> Generated: 2026-03-26

## Authentication

API Key via `X-API-Key` header or `?api_key=` query parameter.
Get a key at https://nzxplorer.co.nz/account

## Base URL

https://nzxplorer.co.nz/api/v1

## Rate Limits

- Free: 10 req/min, 100/day
- Pro ($29/mo): 60 req/min, 1,000/day
- Enterprise ($199/mo): 300 req/min, 10,000/day
- Institutional ($1,250/mo): Custom

## Response Format

All endpoints return JSON. Add `?format=llm` for token-optimized responses.
Large array responses use TOON encoding (tabular, 30-60% fewer tokens).
Responses over 30KB are truncated.

---

## Endpoints

### Company Data

#### GET /companies
Search or list NZX companies.

Parameters:
- search (string, optional): Company name or ticker to search for (e.g. "air new zealand" or "AIR")
- sector (string, optional): Filter by sector (e.g. "Energy", "Healthcare")
- limit (number, optional): Max results (default 10)

Response: Array of company objects with ticker, name, sector, market_cap.

---

#### GET /companies/{ticker}
Get detailed info for a specific NZX company by ticker.

Parameters:
- ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL")
- include (string, optional): Comma-separated includes: directors, financials, governance, price, all

Response: Company object with requested includes.

---

#### GET /governance
Get Governance Risk Scores (GRS) for NZX companies. 0-100 scale across 6 components.

Parameters:
- sector (string, optional): Filter by sector
- min_score (number, optional): Minimum GRS score (0-100)
- max_score (number, optional): Maximum GRS score (0-100)
- rating (string, optional): Filter by rating: Excellent, Very Good, Good, Adequate, Poor, Very Poor
- sort (string, optional): Sort field (e.g. "total_score")
- order (string, optional): "asc" or "desc"
- limit (number, optional): Max results (default 50)

Response: Array of companies with GRS scores and component breakdown (exec remuneration, board structure, shareholder rights, board effectiveness, audit & risk, remuneration disclosure).

---

### Financial Data

#### GET /financials/{ticker}
Get financial statements for an NZX company.

Parameters:
- ticker (string, required): NZX ticker symbol
- statement (string, optional): Statement type: income, balance, cashflow, ratios, or comma-separated (default: all)
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- limit (number, optional): Max results per statement type

Response: Income statement, balance sheet, cash flow, and financial ratios data.

---

#### GET /financials/{ticker}/xbrl
Get machine-readable iXBRL financial statements with IFRS taxonomy tags (54 concepts).

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Fiscal year (default: latest available)

Response: IFRS-tagged income statement, balance sheet, cash flows, ratios.

---

#### GET /earnings/{ticker}
Get structured earnings results extracted from full-year and half-year announcements.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range
- period (string, optional): Period: annual, interim, or all
- limit (number, optional): Max results

Response: Earnings data including revenue, net profit, EBITDA, EPS, DPS, and management guidance.

---

#### GET /earnings-themes/{ticker}
Get AI-extracted themes, tone, and forward-looking statements from earnings announcements.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Themes, management tone, forward-looking statement analysis.

---

#### GET /narrative-tracker/{ticker}
Track how a company's management narrative evolves over time.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Earnings timeline with management tone, key topics, forward-looking statement counts, guidance direction, sentiment scores, AGM Language Intelligence Scores (LIS), and year-over-year shifts.

---

#### GET /dividends/{ticker}
Get dividend history with safety scores and cut probability.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- type (string, optional): Dividend type: final, interim, special
- limit (number, optional): Max results

Response: Dividend history with ex-date, payment date, DPS, imputation %, DRP, Dividend Safety Score (0-100), Forward Dividend Cut Probability (0-100%), payout ratio trends.

---

#### GET /metrics
Get financial metrics/ratios for all NZX companies (list mode).

Parameters:
- sector (string, optional): Filter by sector
- sort (string, optional): Sort by metric (e.g. "pe_ratio", "roe", "dividend_yield")
- order (string, optional): "asc" or "desc"
- year (string, optional): Year or range filter
- limit (number, optional): Max results

Response: Array of companies with 46 financial ratios.

---

#### GET /metrics/{ticker}
Get detailed financial metrics for a specific company with live valuation.

Parameters:
- ticker (string, required): NZX ticker symbol
- mode (string, optional): "snapshot" (default) or "historical"
- year (string, optional): Year or range filter

Response: 46 ratios including profitability (comprehensive_roe, oci_divergence), leverage (paid_in_capital_ratio), cash flow, dividends, growth (share_capital_growth), valuation, composite.

---

#### GET /annual-reports/{ticker}
Get annual and interim report URLs with extraction status.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Fiscal year or range (e.g. "2024" or "2020-2024")
- type (string, optional): Filter: "annual" or "interim"

Response: Report URLs, financial year, extraction status. 2,032 reports available.

---

#### GET /segments/{ticker}
Get revenue segment breakdown by business line/geography.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2025" or "2020-2025")
- type (string, optional): Segment type filter: operating, geographic, product
- limit (number, optional): Max results (default 50)

Response: Segment revenue, operating profit, and assets (all in NZD thousands).

---

#### GET /accounting-quality/{ticker}
Get accounting quality scores.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- limit (number, optional): Max results

Response: Beneish M-score (manipulation risk), Piotroski F-score (financial strength 0-9), Altman Z-score (bankruptcy risk), interest coverage, current ratio. 128 issuers scored.

---

### People & Governance

#### GET /directors
Search NZX company directors.

Parameters:
- company (string, optional): Filter by company ticker
- search (string, optional): Search director name
- current (boolean, optional): Only current directors (default true)
- limit (number, optional): Max results

Response: Array of directors with name, bio, board seats.

---

#### GET /directors/{slug}
Get detailed profile for a specific director.

Parameters:
- slug (string, required): Director slug (e.g. "dame-therese-walsh")
- include (string, optional): Comma-separated: trades, remuneration, exec_comp

Response: Director biography, board seats, compensation, share trades.

---

#### GET /director-report/{slug}
Get comprehensive due diligence report for any NZX director (JSON).

Parameters:
- slug (string, required): Director slug (e.g. "joan-withers", "mark-cross")

Response: All board positions (current + historical), overboarding assessment, remuneration, AGM voting record, insider trading, governance contribution (GRS scores), stock performance during tenure, risk flags.

---

#### GET /director-report/{slug}/pdf
Get director due diligence report as PDF.

Parameters:
- slug (string, required): Director slug

Response: PDF document.

---

#### GET /board-report/{ticker}
Get board composition analytics report (JSON).

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Independence, diversity, tenure, skills matrix, attendance, remuneration, succession risk, turnover, peer benchmarks, risk flags, NZX Code compliance.

---

#### GET /board-report/{ticker}/pdf
Get board composition report as PDF.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: PDF document.

---

#### GET /executive-compensation/{ticker}
Get CEO and executive compensation data.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- role (string, optional): Filter by role (e.g. "CEO", "CFO")

Response: Base salary, STI, LTI, total compensation, shares granted.

---

#### GET /management-team/{ticker}
Get the management team (C-suite executives) for a company.

Parameters:
- ticker (string, required): NZX ticker symbol
- role (string, optional): Filter by normalized role: CEO, CFO, COO, CTO, CIO, CLO, CPO, CMO, CRO, CDO, CS, GM, VP, MD, Other

Response: Current executives with roles, tenure, biographies, education, profile links. 127 issuers, 508 current executives, 15 normalized roles.

---

#### GET /board-changes/{ticker}
Get director appointment, resignation, and retirement events.

Parameters:
- ticker (string, required): NZX ticker symbol
- action (string, optional): Filter by action type: appointed, resigned, retired, removed, elected, re-elected
- from (string, optional): Start date YYYY-MM-DD
- to (string, optional): End date YYYY-MM-DD
- limit (number, optional): Max results (default 50)

Response: Board composition changes with dates and reasons.

---

#### GET /skills-matrix/{ticker}
Get board skills matrix with gap analysis.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 12 skill categories (governance, financial, legal, strategy, technology, industry, risk, esg, international, people, commercial, government) with proficiency levels per director, gap analysis, diversity score. IoD NZ / ASX CGC / AICD aligned.

---

#### GET /board-gap-report/{ticker}
Get comprehensive Board Gap Intelligence Report (JSON).

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Board composition analysis, 12-category skills gap assessment, ideal next director profile, fee benchmarking vs sector, governance scores, risk flags, sector benchmarks.

---

#### GET /board-gap-report/{ticker}/pdf
Get Board Gap Intelligence Report as print-optimized PDF.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: PDF document.

---

#### GET /board-vacancies
Get current board vacancies from Appoint Better Boards and IoD NZ.

Parameters:
- source (string, optional): Filter by source: "appoint" (Appoint Better Boards) or "iod" (IoD NZ)
- sector (string, optional): Filter by sector (e.g. "Health", "Charity/NFP", "Government")
- region (string, optional): Filter by NZ region (e.g. "Auckland", "Wellington", "Canterbury")
- vacancy_id (string, optional): Get details + candidate matches for a specific vacancy ID
- limit (number, optional): Max results (default 20)

Response: Board vacancies with organization, role, sector, region, remuneration type, closing date.

---

#### GET /iod-designations
Get Institute of Directors designated directors on NZX boards.

Parameters:
- designation (string, optional): Filter by IoD designation: "CFInstD", "CMInstD", "CDir", "MInstD"
- ticker (string, optional): Filter by NZX ticker
- name (string, optional): Search by director name
- limit (number, optional): Max results (default 50)

Response: Directors with CFInstD/CMInstD/CDir/MInstD designations and current board seats.

---

#### GET /director-conflicts/{ticker}
Detect conflicts of interest for directors.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Cross-directorships, overboarding risk, related entity overlaps, cross-company insider trading flags.

---

#### GET /interest-register/{ticker}
Get pre-populated interest register for a board per Companies Act 2022 s140.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Per-director external interests: other NZX directorships, charity trustee roles, public sector appointments, substantial shareholdings, recent insider trades, related-party flags.

---

#### GET /director-history/{slug}
Get a director's full company history and failure rate.

Parameters:
- slug (string, required): Director slug (URL-friendly name, e.g. "rob-campbell")

Response: All NZX board positions, biographical company mentions, associations with failed companies (liquidations, receiverships), failure rate percentage, risk level.

---

#### GET /director-network
Analyze director network patterns.

Parameters:
- ticker (string, optional): NZX ticker for company board network mode
- director (string, optional): Director slug or name for director network mode
- include_historical (boolean, optional): Include historical positions (default: false)

Response: Cross-directorships, board interlocks, shared entities. Three modes: company (board network), director (personal network), network (NZX-wide cross-directorship map).

---

#### GET /director-demographics/{ticker}
Get board demographics for a company.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Estimated director ages, international experience (countries worked in), professional body memberships, career length, gender split.

---

#### GET /director-questionnaire/{ticker}/{director_slug}
Get pre-filled D&O insurance questionnaire for a specific director at a company.

Parameters:
- ticker (string, required): NZX ticker symbol
- director_slug (string, required): Director slug (e.g. "rob-campbell", "scott-st-john")

Response: Auto-filled questionnaire (75-85% coverage): all directorships, insider trades, shareholdings, skills matrix, qualifications, committees, regulatory actions, court cases, political connections, career history, board fees.

---

#### GET /director-risk/{slug}
Get composite director risk score for board appointment due diligence.

Parameters:
- slug (string, required): Director slug (e.g. "rob-campbell", "dame-therese-walsh")

Response: Composite 0-100 risk score with 6 weighted sub-scores: failure rate (25%), litigation (20%), regulatory (20%), disciplinary (15%), offshore exposure (10%), overboarding (10%). Rating scale: Low/Moderate/Elevated/High/Critical. Includes signals array describing key risk factors (e.g. "Director associated with 2 failed companies", "3 active court cases") and legal disclaimer. Bulk-optimized with 7 parallel database queries.

---

#### GET /people/{slug}/profile
Get comprehensive cross-platform intelligence report for a person.

Parameters:
- slug (string, required): Person slug from shared.people (e.g. "john-smith")

Response: NZX board roles, charity trusteeships, public sector appointments, iwi roles, MP status, skills matrix, remuneration history, executive compensation, insider trades, governance scores, conflicts, political connections.

---

#### GET /board-effectiveness/{ticker}
Get comprehensive board effectiveness dashboard.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Composition (independence, gender diversity, tenure), skills coverage (12-category heatmap with gaps), governance score (GRS v2.0 + sector percentile), peer benchmarking, succession risk, meeting attendance, remuneration context.

---

#### GET /board-benchmark/{ticker}
Get quantitative board benchmarking vs sector and market-cap peers.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 6 dimensions (board size, independence ratio, gender diversity, skills coverage, meeting frequency, fee levels), percentile rankings, P25/P75 ranges, 3-year trend, strengths/improvements.

---

#### GET /chair-ceo-alignment/{ticker}
Get Chair vs CEO communication alignment analysis.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Language Intelligence Scores comparison, sentiment, conviction, transparency between Chair and CEO AGM speeches, divergence flags, historical trend.

---

#### GET /succession-plan/{ticker}
Get succession risk assessment for a company board.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 5-factor risk model (chair tenure, board fragility, skills concentration, pipeline readiness, sector supply), tenure cohort analysis, skills single-point-of-failure detection, cliff risk, ranked successor candidates.

---

#### GET /first-time-chairs
Get NZX directors serving as board chair for the first time.

Parameters:
- recent_only (boolean, optional): Only show chairs appointed in last 2 years
- sector (string, optional): Filter by sector
- limit (number, optional): Max results (default 50)

Response: Recent first-time chair appointments with prior board experience and governance risk scores.

---

#### GET /board-search
Search across 2,000+ NZX directors and 500+ executives for board/leadership candidates.

Parameters:
- skills (string, optional): Comma-separated skills: financial, strategy, technology, governance, risk_management, legal_compliance, hr_remuneration, sustainability, international, industry_knowledge, stakeholder_relations, digital
- sector (string, optional): Sector experience filter (e.g. "Financials", "Health Care")
- gender (string, optional): Gender filter (male/female)
- max_boards (number, optional): Max current board seats
- available_only (boolean, optional): Only candidates with 2 or fewer boards
- exclude_ticker (string, optional): Exclude candidates on this company
- experience_type (string, optional): Candidate type: board (directors only), executive (execs only), both (default)
- keyword (string, optional): Free-text search on bios/career history (e.g. "Fonterra", "agriculture", "PwC")
- min_fee (number, optional): Min average board fee (NZD)
- max_fee (number, optional): Max average board fee (NZD)
- limit (number, optional): Max results (default 20)

Response: Ranked candidates with match scores, cross-platform experience, career highlights, executive roles.

---

#### GET /committee-chairs
Get board committee membership data.

Parameters:
- committee (string, optional): Filter by committee type (e.g. "Audit", "Risk", "Remuneration", "Nomination")
- ticker (string, optional): Filter by company ticker
- sector (string, optional): Filter by sector
- limit (number, optional): Max results (default 50, max 200)

Response: Committee chairs, types, and composition across NZX companies.

---

#### GET /network-intelligence
Analyze the NZX director network.

Parameters:
- mode (string, required): Analysis mode: "analysis" (full metrics), "shortest-path" (connection path), "power-brokers" (top by centrality), "communities" (governance clusters)
- from (string, optional): Person slug for shortest-path source (e.g. "rob-campbell")
- to (string, optional): Person slug for shortest-path target (e.g. "joan-withers")
- current_only (string, optional): true/false - current appointments only (default: true)
- cross_platform (string, optional): true/false - include charity/public sector connections (default: true)
- limit (number, optional): Max results (default 30)

Response: Connection paths, centrality rankings, governance communities.

---

#### GET /remuneration-benchmarks
Get NZX director compensation benchmarks.

Parameters:
- role (string, optional): Filter by role: "chair", "ned", or "all" (default: "all")
- sector (string, optional): NZX sector name (e.g. "Financials", "Health Care")
- market_cap (string, optional): Size filter: "micro", "small", "mid", "large"
- board_size (string, optional): Board size: "small" (<6), "medium" (6-8), "large" (9+)
- year (number, optional): Specific financial year
- include_trend (string, optional): Include 5-year trend: "true" (default) or "false"

Response: Median, P25/P75 board fees by sector, market cap, and role.

---

#### GET /skill-search
Search the ESCO-aligned skills taxonomy for director skill categories.

Parameters:
- q (string, required): Skill search query (e.g. "cybersecurity", "M&A", "Te Tiriti")
- mode (string, optional): "resolve" (category matches, default), "search" (sub-skill matches), "taxonomy" (full summary)
- limit (number, optional): Max results (default 20)

Response: Matched skill categories from 12 categories with 68 sub-skills.

---

#### GET /insolvency/{slug}
Check insolvency/bankruptcy history for a person via MBIE Insolvency Register.

Parameters:
- slug (string, required): Person slug from shared.people (e.g. "john-smith")

Response: Bankruptcy, no-asset procedures, summary instalment orders. TTL-filtered per MBIE Agreement.

---

#### GET /directorships/{slug}
Get full directorship history from NZ Companies Register.

Parameters:
- slug (string, required): Person slug from shared.people (e.g. "rob-campbell")

Response: All company roles (NZX-listed + private), current and historical, company status, failure rate analysis.

---

### Market Data

#### GET /prices/{ticker}
Get daily stock price history (OHLCV).

Parameters:
- ticker (string, required): NZX ticker symbol
- days (number, optional): Number of recent trading days (default 30)
- from (string, optional): Start date (YYYY-MM-DD)
- to (string, optional): End date (YYYY-MM-DD)

Response: Daily open, high, low, close, volume data.

---

#### GET /insider-trades
Get director share transactions (insider trades).

Parameters:
- ticker (string, optional): Filter by company ticker
- type (string, optional): Transaction type: buy, sell, or all
- days (number, optional): Recent trades within N days
- limit (number, optional): Max results (default 50)

Response: Insider trades with director name, company, transaction type, amount, date.

---

#### GET /announcements
Full-text search across 64,000+ NZX market announcements (2017-present).

Parameters:
- q (string, optional): Search query - searches both titles and full PDF document text
- ticker (string, optional): Filter by company ticker
- type (string, optional): Announcement type: FLLYR, HALFYR, SHINTR, MEETING, GENERAL, SECISSUE, DVDEND, etc.
- from (string, optional): Start date (YYYY-MM-DD)
- to (string, optional): End date (YYYY-MM-DD)
- limit (number, optional): Max results (default 20)

Response: Announcements with title, date, type, ticker, and optional AI fields: ai_sentiment, ai_sentiment_score, ai_topics, ai_risk_flags, ai_summary.

---

#### POST /announcements/{announcement_id}/extract
Read and analyze a specific NZX announcement using AI extraction.

Parameters:
- announcement_id (string, required): The announcement_id from search results

Response: Summary, key figures, sentiment, entities, risk flags. Results cached after first extraction.

---

#### GET /semantic-search
Hybrid semantic + keyword search across NZX announcements using AI embeddings.

Parameters:
- q (string, required): Natural language search query (e.g. "companies discussing supply chain disruption")
- ticker (string, optional): Filter by company ticker
- type (string, optional): Announcement type filter
- from (string, optional): Start date (YYYY-MM-DD)
- to (string, optional): End date (YYYY-MM-DD)
- limit (number, optional): Max results (default 10)

Response: Ranked results combining BM25 keyword matching with vector similarity and Cohere reranking.

---

#### GET /signals
Get the Market Intelligence Feed - unified stream of all NZX market events.

Parameters:
- ticker (string, optional): Filter by company ticker
- type (string, optional): Comma-separated signal types: insider_trade, capital_raise, dividend, earnings, agm_result, director_change, grs_change, technical_signal, credit_rating, audit_change, takeover, board_event, composite_signal
- days (number, optional): Number of days to look back (default 180, use 7 for "this week", 1 for "today")
- significance (string, optional): Filter by significance: high, medium, low
- sector (string, optional): Filter by sector
- limit (number, optional): Max results (default 50)

Response: Array of market signals with type, ticker, date, description, significance.

---

#### GET /anomalies
Get market anomaly detection results - early warning system for unusual patterns.

Parameters:
- ticker (string, optional): Filter by company ticker
- category (string, optional): Filter by category: insider, governance, financial, market, agm
- severity (string, optional): Filter by severity: critical, warning, watch
- sector (string, optional): Filter by sector
- days (number, optional): Number of days to look back (default 180)

Response: 16 anomaly types across 7 categories including insider clusters, governance deterioration, dividend cut risk, technical breakdowns, AGM revolts, sentiment disagreements.

---

#### GET /performance/{ticker}
Get stock performance metrics.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Returns (1d to 5y), alpha vs NZX50, volatility, 52-week range, market cap.

---

#### GET /technical-signals/{ticker}
Get technical analysis indicators.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: SMA-50/100/200, RSI-14, golden/death cross, distance from 52-week high/low, volume ratios.

---

#### GET /takeovers/{ticker}
Get M&A and takeover activity.

Parameters:
- ticker (string, required): NZX ticker symbol
- status (string, optional): Comma-separated: announced, conditional, unconditional, completed, withdrawn, failed
- deal_type (string, optional): Comma-separated: takeover_offer, merger, scheme_of_arrangement, compulsory_acquisition, acquisition
- year (string, optional): Year or range (e.g. "2025" or "2020-2025")
- limit (number, optional): Max results (default 50)

Response: Deal data with acquirer, target, offer price, total value, premium, acceptance %, status, timeline.

---

#### GET /capital-raises/{ticker}
Get capital raise history.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- type (string, optional): Comma-separated raise types: placement, rights_issue, spp, ipo, bond, buyback, drp, options_exercise, employee_scheme, conversion
- buybacks (string, optional): Set to "true" to only show buybacks
- limit (number, optional): Max results

Response: Capital raise events with amounts, pricing, dilution. ~11,700 structured events across 131 issuers.

---

#### GET /capital-raise-sentiment/{ticker}
Analyze whether capital raises were from financial strength or desperation.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Filter by year or range
- type (string, optional): Filter by raise type (comma-separated): placement, rights_issue, spp, ipo, bond, options_exercise
- context (string, optional): Filter by classification: "strength", "neutral", or "desperation"

Response: Per-raise sentiment, financial health, insider activity around +/-30 days, post-raise stock performance (30/90/180 day returns), composite score.

---

#### GET /credit-ratings/{ticker}
Get credit rating history.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range (e.g. "2024" or "2020-2024")
- agency (string, optional): Filter by agency: "S&P", "Moody's", "Fitch", "AM Best"
- action (string, optional): Filter by action: affirmed, upgraded, downgraded, assigned, withdrawn
- limit (number, optional): Max results

Response: Credit ratings with agency, rating, outlook, action type. ~20 NZX companies covered.

---

#### GET /volume-anomalies
Get volume anomaly detection for NZX stocks using z-score analysis.

Parameters:
- ticker (string, optional): NZX ticker symbol to filter (omit for all tickers)
- days (number, optional): Number of days to scan (default: 30, max: 365)
- min_zscore (number, optional): Minimum z-score threshold (default: 2.0)

Response: Volume spikes, clusters (3+ days of >2x avg in 7-day window), price-volume divergences, cross-referenced with announcements within 5 trading days.

---

#### GET /company-changes/{ticker}
Get recent material changes based on AI-extracted announcement data.

Parameters:
- ticker (string, required): NZX ticker symbol
- days (number, optional): Lookback period in days (default 30, max 365)

Response: Revenue, profit, dividend, and guidance changes detected from recent filings.

---

### Ownership Intelligence

#### GET /shareholders/{ticker}
Get top 20 shareholders with holder type classification.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Filter top 20 by fiscal year

Response: 8,594 top-20 records across 101 issuers (2010-2026). Ownership concentration (HHI), holder types (nominee/company/individual/trust/fund), year-over-year changes, substantial holders with voting rights.

---

#### GET /substantial-holders/{ticker}
Get substantial shareholders (5%+ voting rights) from NZX disclosure notices.

Parameters:
- ticker (string, required): NZX ticker symbol
- include_ceased (string, optional): Set to "true" to include former substantial holders

Response: ~267 records across ~85 issuers. Entity name, type, voting rights %, shares held, director/executive status, disclosure dates, threshold crossing history.

---

#### GET /substantial-holders/{ticker}/notices
Get substantial holder notices (SPH) - real-time ownership changes.

Parameters:
- ticker (string, required): NZX ticker symbol
- holder (string, optional): Filter by holder name (e.g. "BlackRock", "ACC")
- direction (string, optional): Filter by direction: increase, decrease, initial, ceased, change
- limit (number, optional): Max results (default 50)

Response: 9,704 classified SHINTR announcements with holder name, type, percentage, direction, fund manager cross-reference.

---

#### GET /beneficial-ownership/{ticker}
Get reconstructed beneficial ownership at fund-level.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Direct holders, nominee breakdowns with identified fund managers, fund holdings, substantial holders. Cross-references top-20 registers with fund manager holdings and custodian mappings.

---

#### GET /kiwisaver-holdings/{ticker}
Get KiwiSaver fund holdings in an NZX company.

Parameters:
- ticker (string, required): NZX ticker symbol
- date (string, optional): Specific quarter date (e.g. "2022-09-30")

Response: KiwiSaver funds holding shares, market value, percentage of fund. Data covers Dec 2018 - Sep 2022.

---

### Proxy Advisory & Research

#### GET /proxy-report/{ticker}
Get AI proxy voting recommendations for AGM resolutions (JSON).

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Meeting year (default: latest meeting)

Response: FOR/AGAINST/REFER recommendation with reasoning for each resolution. 28 rules across 8 categories.

---

#### GET /proxy-report/{ticker}/pdf
Get proxy report as PDF.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: PDF document.

---

#### GET /board-briefing/{ticker}
Get board meeting preparation briefing (9 data sources).

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Governance scores, insider activity, announcements with sentiment, dividend analysis, financial health, peer comparison, AGM status, board changes.

---

#### GET /board-briefing/{ticker}/pdf
Get board briefing as PDF.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: PDF document.

---

#### GET /research/{ticker}
Get AI investment research briefing.

Parameters:
- ticker (string, required): NZX ticker symbol
- template (string, optional): Research template: general (default), investment_thesis, due_diligence, board_meeting, short_thesis
- focus (string, optional): Comma-separated focus areas, e.g. "dividends,governance,insider activity"

Response: AI-synthesized narrative with executive summary, key strengths, risks, outlook. 15+ data sources assembled.

---

#### GET /deep-research/{ticker}
Get deep equity research (35+ proprietary sources, 5 analysis phases).

Parameters:
- ticker (string, required): NZX ticker symbol
- template (string, optional): Research template: general (default), investment_thesis, due_diligence, board_meeting, earnings_preview
- question (string, optional): Specific question to focus the research on

Response: McKinsey-style structured investment report. Takes 30-90 seconds. ~$0.30-0.50/query.

---

#### POST /deep-research/{ticker}
Stream deep research via SSE.

Parameters:
- ticker (string, required): NZX ticker symbol
- template (string, optional): Research template
- question (string, optional): Specific research question

Response: Server-Sent Events stream with progressive research output.

---

#### GET /deep-research-qa/{ticker}
Validate a deep research report against ground-truth NZXplorer data.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Per-check pass/fail/warn status, overall confidence score (0-100), critical failures. Cross-checks financials, governance, accounting quality, director counts, ESG.

---

#### GET /broker-coverage/{ticker}
Get analyst/broker coverage.

Parameters:
- ticker (string, required): NZX ticker symbol
- include (string, optional): Comma-separated sections: ratings, forecasts, reports, summary, all (default: ratings,summary)

Response: Broker and analyst coverage, ratings (buy/hold/sell), price targets, earnings forecasts, recommendation distribution, consensus summary.

---

#### GET /estimates/{ticker}
Get unified analyst consensus estimates.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Yahoo Finance consensus (target prices, buy/hold/sell), company guidance (revenue/NPAT/EBITDA with accuracy history), individual broker ratings, earnings surprise probability, valuation context.

---

#### GET /company-pager/{ticker}
Generate a one-page company snapshot.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Key financial metrics, governance score, dividend data, insider activity, risk flags, recent announcements. Also available as PDF at /company-pager/{ticker}/pdf.

---

#### GET /fund-votes/{ticker}
Get actual voting records from NZ fund managers.

Parameters:
- ticker (string, required): NZX ticker symbol
- fund_manager (string, optional): Filter by fund manager name (e.g. "Harbour", "Devon")
- year (string, optional): Year or range (e.g. "2024" or "2023-2025")
- vote (string, optional): Filter by vote type: FOR, AGAINST, ABSTAIN
- limit (number, optional): Max results (default 50)

Response: How institutional investors (Harbour, Devon, Mint, Fisher, NZ Super) voted on AGM resolutions.

---

#### GET /stewardship-reports
List FMA-compliant stewardship/voting-record reports. Enterprise tier required.

Parameters: None

Response: Report summaries with vote counts, compliance rates, period dates.

---

#### GET /stewardship-reports/{id}
Get full detail for a specific stewardship report. Enterprise tier required.

Parameters:
- id (number, required): Stewardship report ID

Response: Per-company resolution analysis, vote recommendations, policy used.

---

#### GET /voting-policies
List all custom voting policies. Enterprise or Institutional tier required.

Parameters: None

Response: Voting policies with threshold overrides for proxy advisory engine.

---

### Search

#### GET /keyword-trends
Search keyword frequency trends across 64,000+ NZX announcements.

Parameters:
- keyword (string, optional): Single keyword or phrase (e.g. "artificial intelligence", "restructuring")
- keywords (string, optional): Comma-separated keywords for comparison (max 5, e.g. "ai,climate,esg")
- ticker (string, optional): Filter to a specific company ticker

Response: Frequency by year with adoption rate and YoY growth, sector breakdown, top companies with first mention date.

---

#### GET /risk-language/{ticker}
Get pre-computed risk language scores.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 8 risk categories (going_concern, covenant, impairment, litigation, restructuring, liquidity, regulatory, force_majeure) with total mentions, 12-month trend, category breakdown, critical flags, first-time detections, yearly trend.

---

### Screener

#### GET /screener
266-column screener with 51 presets.

Parameters:
- preset (string, optional): Smart preset: value, growth, quality, dividend_risk, insider_buying, capital_raise, ceo_pay_failure, governance_laggards, oversold, overbought, golden_cross, below_200ma, dividend_aristocrats, low_volatility, turnaround, small_cap_gems, death_cross, income_portfolio, conservative_growth, esg_compliant, rate_sensitive, property_reits, and more
- filter (string, optional): Custom metric filters, comma-separated. Format: metric>value or metric<value. Examples: "pe_ratio<15,dividend_yield>3", "rsi_14<30", "grs_score>70,roe>15"
- sector (string, optional): Filter by sector (e.g. "Energy", "Healthcare", "Utilities")
- q (string, optional): Search by company name or ticker
- sort (string, optional): Sort by any metric (e.g. "rsi_14", "pe_ratio", "dividend_yield", "grs_score", "return_1y")
- order (string, optional): Sort direction: "asc" or "desc" (default "desc")
- limit (number, optional): Max results (default 50, max 500)

Response: Array of companies with screener metrics matching filters.

---

### ESG & Corporate

#### GET /esg/{ticker}
Get ESG metrics and scores.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Filter by fiscal year

Response: 255 emissions records, 760 diversity records, 270 safety records. Includes emissions (scope 1/2/3, targets, verification), diversity (board/SLT/employee gender, Maori/Pasifika), safety (LTIFR/TRIFR, fatalities, FTE), reporting standards (GRI/TCFD/SBTi).

---

#### GET /esg/{ticker}/xbrl
Get NZ Climate Standards tagged ESG/climate disclosure.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Fiscal year (default: latest available)

Response: Emissions (Scope 1/2/3), diversity metrics, safety data, reporting framework compliance in machine-readable format.

---

#### GET /climate-gap-analysis/{ticker}
Get NZ Climate Standards (NZ CS 1-4) gap analysis.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 23 XRB requirements assessed across governance (5), strategy (6), risk management (4), metrics & targets (8). Per-requirement status (met/partial/gap), evidence, recommendations, overall score (0-100), mandatory reporter status.

---

#### GET /esg-disclosure-gap/{ticker}
Get multi-framework ESG disclosure gap analysis.

Parameters:
- ticker (string, required): NZX ticker symbol
- framework (string, optional): Filter to specific framework: tcfd, issb, nzcs, all (default: all)

Response: Comparison against TCFD (11 recommendations), ISSB/IFRS S2, and NZ XRB Climate Standards. Per-framework scores, requirement-level gaps, mandatory reporter status, multi-framework readiness score.

---

#### GET /audit-history/{ticker}
Get audit opinion history and red flags.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Auditor name/firm, opinion type (unmodified/qualified/adverse/disclaimer), going concern warnings, emphasis of matter, key audit matters, audit/non-audit fees, risk signals.

---

#### GET /ir-quality/{ticker}
Get IR Quality Score (IRQS) - disclosure quality measurement.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 0-100 score across 5 dimensions: timeliness, completeness, readability, frequency, governance transparency. 131 issuers scored. Includes trajectory (improving/stable/declining).

---

#### GET /corporate-giving/{ticker}
Get corporate donations, sponsorships, and community investment.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Recipients, amounts, donation types (cash/sponsorship/community_investment/grant/in-kind), foundation name, total community investment. Cross-linked to registered charities.

---

#### GET /corporate-relationships/{ticker}
Get all professional service relationships.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Auditors, law firms, share registrars, bankers. Current and historical relationships, audit fee data, companies sharing same advisers.

---

### Intelligence

#### GET /peer-mentions/{ticker}
Get peer mention network with 10 relation types.

Parameters:
- ticker (string, required): NZX ticker symbol
- direction (string, optional): "mentions" (companies this ticker references), "mentioned_by" (companies referencing this ticker), or "both" (default)
- relation (string, optional): Filter by relation type(s), comma-separated (e.g. "supplier,customer")

Response: Peer mention network extracted from 62,000+ documents. Relation types: supplier, customer, partner, competitor, joint_venture, acquirer, subsidiary, licensee, advisor, shareholder. Context snippets and confidence levels.

---

#### GET /political-connections/{ticker}
Get political connections for a company.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: MP interests (gifts, hospitality, shareholdings, travel), political donors linked to company/directors, party donation records. Data from Parliamentary Register and Electoral Commission.

---

#### GET /councillor-interests/{council_slug}
Get pecuniary interests declared by councillors.

Parameters:
- council_slug (string, required): Council slug (e.g. "wellington-city-council", "auckland-council")
- term (string, optional): Filter by council term (e.g. "2025-2028")
- include (string, optional): Comma-separated extras: "entities" (top entities), "summary" (aggregate stats)

Response: Financial interests per Local Authorities (Members' Interests) Act 1968. Company directorships, shareholdings, trusts, property, employment, gifts, organization memberships.

---

#### GET /management-credibility/{ticker}
Get management credibility score (0-100).

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Composite score based on 4 factors: guidance accuracy (did they hit targets?), tone consistency (stable vs erratic), insider trading alignment, guidance transparency.

---

#### GET /macro-regime
Get current NZ macroeconomic regime.

Parameters: None

Response: RBNZ OCR rate and cycle direction, GDP growth, CPI inflation, unemployment rate, NZD exchange rates, US Fed Funds, US 10Y Treasury.

---

#### GET /macro-exposure/{ticker}
Get company-specific macro sensitivity profile.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: OCR sensitivity, FX exposure, cyclicality, composite macro risk score (0-100).

---

#### GET /macro-indicators
Get historical time series for macro indicators.

Parameters:
- code (string, optional): Indicator code: RBNZ_OCR, NZ_GDP_QOQ, NZ_CPI_YOY, NZ_UNEMPLOYMENT, NZ_HOUSE_PRICE_YOY, US_FED_FUNDS, UST_10Y, VIX, NZD_USD, NZD_AUD, NZD_TWI
- category (string, optional): Category filter: growth, inflation, employment, housing, global, fx, monetary_policy
- from (string, optional): Start date (YYYY-MM-DD)
- to (string, optional): End date (YYYY-MM-DD)

Response: Historical time series data for selected indicator(s).

---

#### GET /property-portfolio/{ticker}
Get property portfolio data for NZX-listed REITs.

Parameters:
- ticker (string, required): NZX ticker symbol (KPG, ARG, PFI, VHP, IPL, SPG, CDI, GMT, PCT, APL)

Response: Individual properties with book values, cap rates, WALE, occupancy, tenants, locations, climate risk scores. Portfolio summary, type/regional breakdowns, development pipeline.

---

#### GET /news-sentiment/{ticker}
Get AI-scored news sentiment from NZ financial media.

Parameters:
- ticker (string, required): NZX ticker symbol
- days (number, optional): Number of days to look back (default 30)
- source (string, optional): Filter by source: "interest", "nzherald", "rnz", "nbr", "stuff"

Response: 7d/30d averages, sentiment distribution, top topics, recent scored articles.

---

#### GET /sentiment/{ticker}
Get AI-scored announcement sentiment.

Parameters:
- ticker (string, required): NZX ticker symbol
- sentiment (string, optional): Filter: positive, negative, neutral, mixed
- hedging (string, optional): Filter by hedging level: none, low, moderate, heavy
- from (string, optional): Start date (YYYY-MM-DD)
- to (string, optional): End date (YYYY-MM-DD)
- limit (number, optional): Max results (default 20)

Response: Per-announcement sentiment scores (-1 to +1), confidence, hedging level, buried risks, key topics, guidance direction, company-level summary.

---

#### GET /factor-grades/{ticker}
Get A-F factor grades across 6 dimensions.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Value (PE/PB/EV vs sector), Growth (revenue/profit), Profitability (ROE/margins), Momentum (price returns), Dividends (yield/safety/payout), Governance (GRS). Sector-relative percentile ranking, composite grade.

---

#### GET /factor-model
Get NZ Equity Factor Model - market-wide 6-factor scores for all companies.

Parameters:
- sector (string, optional): Filter by sector
- factor (string, optional): Sort by: value, growth, profitability, momentum, dividends, governance
- grade (string, optional): Filter by composite grade (e.g. "A,B")
- limit (number, optional): Limit results (default: all)

Response: Sector-relative percentile ranking (0-100) with A-F grades for all NZX companies.

---

#### GET /alpha-score/{ticker}
Get composite alpha score (0-100).

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Score combining 5 proprietary signals: governance, insider conviction, management credibility, financial quality, dividend sustainability. Rating (Strong Alpha/Moderate Alpha/Neutral/Moderate Risk/High Risk), component breakdown, validated alpha spreads.

---

#### GET /fair-value/{ticker}
Get estimated fair value using 3 valuation models.

Parameters:
- ticker (string, required): NZX ticker symbol
- discount_rate (number, optional): Discount rate / WACC (default 0.10 = 10%)
- terminal_growth (number, optional): Terminal growth rate (default 0.025 = 2.5%)

Response: DCF, Dividend Discount Model, EV/EBITDA relative valuation. Composite fair value per share, price-to-fair-value ratio, confidence level, methodology notes. NOT a target price or investment recommendation.

---

#### GET /earnings-surprise/{ticker}
Get earnings surprise probability.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 9-factor model prediction (calibrated from 716-event backtest). Surprise probability (0-100%), direction (upside/downside/inline), risk level, factor breakdown. Factors: guidance accuracy, tone consistency, analyst consensus, historical beat/miss, insider alignment, transparency, volatility, capital stress, forward-looking density.

---

#### GET /liquidity/{ticker}
Get Kyle's Lambda liquidity score.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Price impact per unit of volume using Kyle (1985) regression. Liquidity rating (A-E), average daily volume, average daily traded value, volume trend.

---

#### GET /ir-dashboard/{ticker}
Get comprehensive Investor Relations dashboard.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: 9 data sources combined: IR Quality Score, announcement sentiment (6mo trend), substantial shareholder composition (HHI), insider trading activity (12mo), governance risk scores, earnings trajectory, disclosure frequency, sector peer benchmarking.

---

#### GET /agm-resolutions/{ticker}
Get AGM resolution voting data.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Filter by meeting year

Response: Resolutions, votes for/against/abstain, pass/fail status, support percentages.

---

#### GET /agm-speeches/{ticker}
Get AGM speech analysis with Language Intelligence Score (LIS).

Parameters:
- ticker (string, required): NZX ticker symbol
- year (string, optional): Year or range
- role (string, optional): Filter by speaker role (e.g. "Chair", "CEO")

Response: Sentiment, conviction, hedging, key themes per speech.

---

#### GET /simulate-event/{ticker}
Simulate a hypothetical event and estimate impact.

Parameters:
- ticker (string, required): NZX ticker symbol
- event_type (string, required): Type: ceo_departure, ocr_change, major_customer_loss, dividend_cut, earnings_miss, acquisition, regulatory_action, director_resignation, capital_raise, credit_downgrade
- ocr_change (number, optional): For ocr_change: basis point change (e.g. -25 or +50)
- customer_name (string, optional): For major_customer_loss: customer name

Response: Estimated impact on share price, revenue, governance, and stakeholders using actual company data and NZX historical precedents. $0 cost.

---

#### POST /ir-rehearsal/{ticker}
Analyze a draft NZX announcement before publication.

Parameters:
- ticker (string, required): NZX ticker symbol
- draft_text (string, required): Draft announcement text (50-50,000 characters)

Response: FMA compliance risks, defamation language detection, forward-looking statement count, hedging analysis, market sentiment prediction, media pickup probability, analyst follow-up questions, readability. $0 cost.

---

#### POST /narrative-risk/{ticker}
Multi-stakeholder narrative risk simulation for a draft announcement.

Parameters:
- ticker (string, required): NZX ticker symbol
- draft_text (string, required): Draft announcement text (50-50,000 chars)

Response: Composite risk score (0-100), stakeholder reactions (institutions, retail, media, analysts, regulators), signal conflicts, recommended IR actions, reaction timeline. ~$0.10.

---

#### GET /agm-predictor/{ticker}
Predict AGM resolution outcomes.

Parameters:
- ticker (string, required): NZX ticker symbol
- year (number, optional): Meeting year to predict (defaults to latest)
- resolution_type (string, optional): Category filter: director_election, remuneration, auditor, capital_management, constitution, related_party, shareholder_proposal

Response: Predicted support %, swing voters, risk factors, historical comparisons. Uses fund manager voting records and ownership composition. $0 cost.

---

#### GET /thesis/{ticker}
Check if an investment thesis is still valid.

Parameters:
- ticker (string, required): NZX ticker symbol
- direction (string, required): Your thesis direction: bullish, bearish, neutral

Response: Invalidation score (0-100), comparison against 4 signals: analyst consensus, fair value model, management credibility, insider activity.

---

### Corporate Risk Intelligence

#### GET /regulatory-actions/{ticker}
Get regulatory enforcement actions.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Enforcement history from FMA, Commerce Commission, NZX. Penalties, severity, prohibited director flags.

---

#### GET /prohibited-directors
Get full list of prohibited/banned directors from Companies Office register.

Parameters: None

Response: Prohibited persons with any matches to current NZX directors.

---

#### GET /litigation/{ticker}
Get court litigation history.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Cases from High Court, Court of Appeal, Supreme Court. Case type, outcome, dates, damages.

---

#### GET /professional-disciplinary/{ticker}
Get professional body disciplinary records for directors.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Records from CA ANZ, NZ Law Society, Medical Council, Engineering NZ. Action type, severity, outcome, match confidence.

---

#### GET /offshore-exposure/{ticker}
Get ICIJ Offshore Leaks Database matches.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Panama Papers, Pandora Papers, Paradise Papers, Bahamas Leaks matches for directors and entities. Match scores and review status.

---

#### GET /select-committee/{ticker}
Get NZ Parliament select committee activity for a company.

Parameters:
- ticker (string, required): NZX ticker symbol

Response: Committee reports mentioning the company (annual reviews, inquiries, bills) and company submissions to parliament. 1990 to present.

---

### Deal Intelligence

#### GET /deal-advisers/{ticker}
Get professional advisers on capital raises and takeovers.

Parameters:
- ticker (string, required): NZX ticker symbol
- deal_type (string, optional): Filter by deal type: capital_raise or takeover
- role (string, optional): Filter by adviser role: legal_issuer, underwriter, lead_manager, independent_adviser, valuer, etc.

Response: Law firms, investment banks, valuers with roles on each deal. Deal details (amount, type, date).

---

#### GET /deal-insider-signals/{ticker}
Detect insider trading patterns before capital raises and takeovers.

Parameters:
- ticker (string, required): NZX ticker symbol, or "all" for market-wide scan
- days (number, optional): Lookback window before deal: 30, 60, or 90 (default 90)
- deal_type (string, optional): Filter: capital_raise or takeover

Response: Signal type (buy/sell/mixed), severity, volume anomaly vs 12-month average, individual director activity.

---

#### GET /deal-prediction/{ticker}
Score company 0-100 for likelihood of capital raise in next 12 months.

Parameters:
- ticker (string, required): NZX ticker symbol or "all" for market-wide rankings

Response: 8-factor model score: raise frequency, recency, cash position, debt pressure, insider buying, dividend stress, adviser appointments, capex needs.

---

#### GET /adviser-market-share
Get NZX deal adviser league tables.

Parameters: None

Response: Annual and quarterly market share rankings by deal count and value. Law firms, investment banks, accounting firms. Sector specialization and historical trends.

---

#### GET /deal-conflicts/{ticker}
Detect potential conflicts of interest in NZX capital markets deals.

Parameters:
- ticker (string, required): NZX ticker symbol or "all" for market-wide scan

Response: Cross-references deal advisers with director appointments, MP interests, auditor independence, councillor declarations.

---

### Government & Public Sector

#### GET /government-contracts/{ticker}
Get government contracts awarded to an NZX-listed company via GETS.

Parameters:
- ticker (string, required): NZX ticker symbol
- limit (number, optional): Max contracts (default 100, max 500)
- from (string, optional): Filter contracts awarded on or after date (YYYY-MM-DD)

Response: Contract history, agencies, values, government revenue exposure.

---

### Alerts & Webhooks

#### GET /alerts/subscriptions
List alert subscriptions for the authenticated user.

Parameters: None

Response: Alert configurations with tickers, sectors, signal types, anomaly categories, severity levels, delivery methods.

---

#### POST /alerts/subscriptions
Create alert subscription. 11 signal types, 7 anomaly categories.

Parameters: See POST body schema in API documentation.

Response: Created subscription object.

---

#### GET/PATCH/DELETE /alerts/subscriptions/{id}
Manage a specific alert subscription.

Parameters:
- id (string, required): Subscription ID

---

#### GET /webhooks
List webhooks. Enterprise tier required.

Parameters: None

Response: Array of webhook configurations.

---

#### POST /webhooks
Create webhook with filters. Enterprise tier required.

Parameters: See POST body schema in API documentation.

Response: Created webhook object.

---

#### GET/PUT/DELETE /webhooks/{id}
Manage a specific webhook.

Parameters:
- id (string, required): Webhook ID

---

#### GET /webhooks/{id}/history
Get webhook delivery history.

Parameters:
- id (string, required): Webhook ID

Response: Delivery attempts with status codes and timestamps.

---

#### POST /webhooks/{id}/test
Test webhook payload delivery.

Parameters:
- id (string, required): Webhook ID

Response: Test delivery result.

---

#### GET /announcement-alerts
List announcement alert subscriptions for the authenticated user.

Parameters: None

Response: Active alert configurations for content matching by keyword, type, ticker, sector.

---

#### POST /announcement-alerts
Create announcement alert.

Parameters: See POST body schema (keyword/type/ticker/sector filters).

Response: Created alert object.

---

#### GET /watchlist
Get the authenticated user's watchlists.

Parameters: None

Response: Watchlists with names and tickers.

---

#### GET /keyword-alerts
Get the authenticated user's keyword alerts and recent matches.

Parameters:
- include_matches (boolean, optional): Include recent alert matches (default false)

Response: Alert configurations and matched announcements.

---

#### GET /morning-brief
Get or generate a morning brief for watchlist companies.

Parameters:
- date (string, optional): Get brief for specific date (YYYY-MM-DD)
- generate (boolean, optional): Generate today's brief on demand (default false)
- days (number, optional): Lookback days for generation (default 1)

Response: Overnight announcements, insider trades, price moves, dividends, governance changes.

---

#### GET /portfolio/enriched
Get the authenticated user's portfolio holdings with enriched data.

Parameters: None

Response: Current prices, unrealized P&L, GRS scores, dividend yields, risk flags, upcoming events, recent insider trades, sector exposure breakdown.

---

### Widgets

#### GET /widgets/{type}
Get embeddable widgets.

Parameters:
- type (string, required): Widget type: price-card, governance-badge, dividend-history, insider-activity, financials-summary, company-overview, sector-heatmap

Response: Widget HTML/data for embedding.

---

#### GET /sector-heatmap
Get standalone sector performance data.

Parameters: None

Response: Sector performance data for heatmap visualization.

---

### Bulk Data

#### GET /downloads/{dataset}
Download datasets. Enterprise tier required.

Parameters:
- dataset (string, required): Dataset name (13 available)
- ticker (string, optional): Filter by ticker
- year (string, optional): Filter by year
- sector (string, optional): Filter by sector

Response: Dataset in requested format.

---

#### GET /export/xlsx
XLSX export. 6 dataset types.

Parameters:
- type (string, required): Dataset type

Response: XLSX file download.

---

#### GET /institutional-ownership/{ticker}
KiwiSaver + institutional ownership panel. Returns unified view of all ownership data for a company.

Parameters:
- ticker (string, required): NZX ticker symbol

Response includes:
- summary: kiwisaver_fund_count, kiwisaver_total_value, institutional_holder_count, top5_concentration_pct, nominee_pct
- kiwisaver_holders: fund_name, manager_name, fund_category, percent_of_fund, market_value
- institutional_holders: fund_manager, manager_type, aum_nzd, weight_pct, shares_held
- top_20_shareholders: holder_name, holder_type, shares_held, percentage
- beneficial_ownership: see-through nominee data

---

#### GET /vote-history
Historical vote comparison across funds. Shows how different funds voted on the same resolutions.

Parameters:
- ticker (string): Filter by company
- fund (string): Filter by fund name
- year (string): Filter by meeting year (e.g. "2025")
- dissent_only (boolean): Only show resolutions where funds disagreed

Response includes:
- summary: total_resolutions, dissent_count, dissent_rate, funds_compared
- resolutions: grouped by meeting+resolution with fund_votes array
- vote_changes: historical vote modifications from vote_history table

---

#### GET /compliance-audit
Institutional compliance audit trail export. Returns all API activity for the authenticated user/key.

Parameters:
- from (string, required): Start date (YYYY-MM-DD)
- to (string, required): End date (YYYY-MM-DD)
- entity_type (string): Filter by entity type
- action (string): Filter by action
- format (string): "json" (default) or "csv"
- limit (integer): Max rows (default 1000, max 10000)

Response: JSON or CSV file download with timestamp, action, entity_type, endpoint, status_code, ip_address.

---

## MCP Server

131 tools available via Model Context Protocol.

### Installation
```
npx nzxplorer-mcp
```

### Configuration
Add to your MCP client config (e.g. Claude Desktop):
```json
{
  "mcpServers": {
    "nzxplorer": {
      "command": "npx",
      "args": ["nzxplorer-mcp"],
      "env": {
        "NZXPLORER_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Protocol
- Transport: stdio (local) or SSE (remote, coming soon at mcp.nzxplorer.co.nz)
- Tools map 1:1 with API endpoints listed above
- Tool names use snake_case (e.g. `get_company_detail`, `screen_stocks`)
- All tools return JSON responses

---

## AI Copilot

### POST /ask
Natural language queries about any NZX company. SSE streaming.

131 tools available. The AI agent selects appropriate tools based on user queries.

### Headers
- X-API-Key (required): Your API key
- Content-Type: application/json

### Body
```json
{
  "message": "What is the governance score for Fisher & Paykel Healthcare?",
  "history": [],
  "stream": true
}
```

### Response
Server-Sent Events stream with progressive AI response.

### Cost
~$0.03-0.15 per query depending on tools invoked.

---

## Data Coverage

- 131 NZX-listed companies
- 2,277 directors with skills, qualifications, remuneration
- 3,257 executive records (508 current, 15 normalized roles)
- 64,442 indexed announcements (62,500+ with extracted PDF text)
- 2,032 annual/interim reports (FY2010-2025)
- 9,453 insider trades
- 8,594 top-20 shareholder records (101 issuers, 2010-2026)
- 1,079 structured earnings results
- 30+ years stock price history
- 615 REIT property assets (10 companies)
- 1,285 ESG records (emissions, diversity, safety)
- 938 structured guidance records with accuracy scores
- 133 regulatory enforcement actions
- 206 professional disciplinary records
- 7,805 councillor interest records (57/78 councils)
- 771 political donors, 1,005 party donations
- 56 fund managers, 1,461 fund holdings

---

## Links

- API Documentation: https://nzxplorer.co.nz/developers
- Product Docs: https://nzxplorer.co.nz/docs
- Pricing: https://nzxplorer.co.nz/pricing
- OpenAPI Spec: https://nzxplorer.co.nz/openapi.json
- Summary: https://nzxplorer.co.nz/llms.txt
- Contact: hello@nzxplorer.co.nz