# NZXplorer — Full API Reference (llms-full.txt) > Machine-readable API specification for AI agent integration. > Summary version: /llms.txt | Agent guide: /for-agents | OpenAPI spec: /openapi.json > Generated dynamically from the live tool registry: 2026-06-13 (188 tools — cannot drift from the shipped API) ## Authentication API Key via `X-API-Key` header or `?api_key=` query parameter. Get a free key at https://nzxplorer.co.nz/account No-signup option: the remote MCP endpoint at https://mcp.nzxplorer.co.nz (anonymous tier — 30 read-only tools, 30 calls/hour and 100/day per IP). ## Base URL https://nzxplorer.co.nz/api/v1 ## Rate Limits - Free: 10 req/min - Pro ($29/mo): 60 req/min - Enterprise ($199/mo): 300 req/min - Institutional ($1,250/mo): Custom ## Response Format All endpoints return JSON. Add `?format=llm` for token-optimized responses (~70% fewer tokens). Large array responses use TOON encoding (tabular, 30-60% additional savings). Responses over 30KB are truncated. ## Markdown Mirrors Per-entity markdown twins (clean markdown, stable URLs, ideal for citation): - /api/v1/companies/{ticker}/markdown - /api/v1/governance-scorecard/{ticker}/markdown - /api/v1/proxy-report/{ticker}/markdown - /api/v1/announcements/{id}/markdown - /api/v1/dividends/{id}/markdown ## Tools / Endpoints Each tool below maps 1:1 to a REST endpoint (shown with its path and query parameters) and is also callable via MCP (remote: https://mcp.nzxplorer.co.nz, local: `npx -y nzxplorer-mcp`) and the AI Copilot. --- #### search_companies GET /api/v1/companies — query: search, sector, limit Search NZX-listed companies by name or ticker. Returns company list with sector, market cap. Use this to find a company ticker before calling other tools. 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) --- #### get_company_detail GET /api/v1/companies/{ticker} — query: include Get detailed info for a specific NZX company by ticker. Can include directors, financials, governance score, and latest stock price. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") - include (string, optional): Comma-separated includes: directors, financials, governance, price, all (e.g. "governance,price") --- #### get_governance_scores GET /api/v1/governance — query: sector, min_score, max_score, rating, sort, order, limit Get Governance Risk Scores (GRS) for NZX companies. 0-100 scale across 6 components: exec remuneration, board structure, shareholder rights, board effectiveness, audit & risk, remuneration disclosure. Can filter by sector, rating, or score range. 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) --- #### get_financials GET /api/v1/financials/{ticker} — query: statement, year, limit Get financial statements for an NZX company. Includes income statement, balance sheet, cash flow, and financial ratios. Filter by statement type and year range. 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 --- #### get_financials_xbrl GET /api/v1/financials/{ticker}/xbrl — query: year Get machine-readable iXBRL financial statements for an NZX company. Returns IFRS taxonomy-tagged data (income statement, balance sheet, cash flows, ratios). Use when the user wants structured/machine-readable financial data, XBRL output, or data for programmatic consumption. Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Fiscal year (default: latest available) --- #### get_esg_xbrl GET /api/v1/esg/{ticker}/xbrl — query: year Get machine-readable NZ Climate Standards (NZ CS) tagged ESG/climate disclosure for an NZX company. Returns emissions (Scope 1/2/3), diversity metrics, safety data, and reporting framework compliance. Use when the user wants ESG data, climate disclosures, emissions, diversity stats, or sustainability data in structured format. Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Fiscal year (default: latest available) --- #### get_metrics GET /api/v1/metrics/{ticker} — query: mode, year Get financial metrics/ratios for NZX companies. 46 ratios: profitability (incl. comprehensive_roe, oci_divergence), leverage (incl. paid_in_capital_ratio), cash flow, dividends, growth (incl. share_capital_growth), valuation, composite. Use for screening or comparison. Parameters: - ticker (string, optional): Specific ticker for detailed metrics with live valuation. Omit for list of all companies. - sector (string, optional): Filter by sector (list mode only) - sort (string, optional): Sort by metric (e.g. "pe_ratio", "roe", "dividend_yield") - order (string, optional): "asc" or "desc" - mode (string, optional): For single ticker: "snapshot" (default) or "historical" - year (string, optional): Year or range filter - limit (number, optional): Max results --- #### get_insider_trades GET /api/v1/insider-trades — query: ticker, type, days, limit Get director share transactions (insider trades) for NZX companies. Shows who is buying/selling, amounts, and dates. 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) --- #### get_dividends GET /api/v1/dividends/{ticker} — query: year, type, limit Get dividend history for an NZX company. Includes ex-date, payment date, amount (DPS), imputation %, DRP availability, summary stats. Company pages also show Dividend Safety Score (0-100 with 5 components), Forward Dividend Cut Probability (0-100% with risk factors), and Payout Ratio Trend Charts with sector benchmarks. 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 --- #### get_dividend_stress_test GET /api/v1/dividend-stress/{ticker} — query: scenarios Stress-test dividend safety under recession scenarios. Models what happens to the Dividend Safety Score if earnings decline 20%, 30%, or 50%. Returns base vs stressed DSS, breakpoint (the earnings decline % where DSS drops below Moderate), recession resilience rating (Strong/Adequate/Vulnerable/Fragile), and sector-typical recession context. Answers: "Is the dividend safe in a recession?" Use custom scenarios param for specific decline levels. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - scenarios (string, optional): Comma-separated earnings decline percentages (default "20,30,50"). E.g. "10,25,40" --- #### get_earnings GET /api/v1/earnings/{ticker} — query: year, period, limit Get earnings results for an NZX company. Extracted from full-year and half-year announcements. Includes revenue, net profit, EBITDA, EPS, DPS, and management guidance. 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 --- #### get_board_changes GET /api/v1/board-changes/{ticker} — query: action, from, to, limit Get director appointment, resignation, and retirement events for an NZX company. Shows board composition changes over time with dates and reasons. Parameters: - ticker (string, required): NZX ticker symbol (e.g., FPH, AIR) - 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) --- #### get_stock_prices GET /api/v1/prices/{ticker} — query: days, from, to Get daily stock price history (OHLCV) for an NZX company. Use for price trends, returns, and technical context. 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) --- #### search_announcements GET /api/v1/announcements — query: q, ticker, type, from, to, limit Full-text search across 64,000+ NZX market announcements (2017-present), including 62,500+ with extracted PDF text. Searches announcement titles AND full document content. Use for finding mentions of specific topics, companies, people, or events across all NZX filings. Results include: ai_category (25-category AI classification like M&A, Dividend, Regulatory, Capital Raise, Guidance, Earnings Results), ai_category_confidence (0.0-1.0), ai_sub_topics (1-3 topic tags). May also include: ai_sentiment (positive/negative/neutral/mixed), ai_sentiment_score (-1.0 to 1.0), ai_topics (array of topic labels), ai_risk_flags (array of risk indicators like profit_warning, dividend_cut), and ai_summary (concise summary). 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) --- #### read_announcement POST /api/v1/announcements/{announcement_id}/extract Read and analyze a specific NZX announcement. Extracts summary, key figures, sentiment, entities, and risk flags using AI. Provide the announcement_id (e.g. "12345") from search_announcements results. Returns cached results if previously extracted. Parameters: - announcement_id (string, required): The announcement_id from search_announcements results --- #### search_semantic GET /api/v1/semantic-search — query: mode, rerank, q, ticker, type, from, to, limit Hybrid semantic + keyword search across NZX announcements. Uses AI embeddings to find conceptually related filings, even if exact keywords differ. Better than search_announcements for: vague queries ("companies discussing AI strategy"), conceptual searches ("climate risk disclosures"), finding similar announcements, and queries where exact keyword matches miss relevant results. Combines BM25 keyword matching with vector similarity and Cohere reranking for best results. 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) --- #### get_directors GET /api/v1/directors — query: company, search, current, limit Search NZX company directors. Returns name, bio, board seats. Filter by company or search by name. 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 --- #### get_director_detail GET /api/v1/directors/{slug} — query: include Get detailed profile for a specific director by slug. Includes biography, board seats, compensation, share trades. Parameters: - slug (string, required): Director slug (e.g. "dame-therese-walsh") - include (string, optional): Comma-separated: trades, remuneration, exec_comp --- #### get_executive_compensation GET /api/v1/executive-compensation/{ticker} — query: year, role Get CEO and executive compensation for an NZX company. Shows base salary, STI, LTI, total compensation, shares granted. Use this for pay analysis and pay-for-performance questions. 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") --- #### get_shareholders GET /api/v1/shareholders/{ticker} — query: year Get top 20 shareholders and substantial holders (5%+) for an NZX company. 9,284 top-20 records across 120 issuers with multi-year history (2010-2026) plus ~267 substantial holders from NZX disclosure notices. Shows ownership concentration (HHI index), holder types (nominee/company/individual/trust/fund), year-over-year ownership changes, and substantial holders with voting rights percentages. Use ?year=2025 or ?all=true for historical data. Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Filter top 20 by fiscal year --- #### get_substantial_holders GET /api/v1/substantial-holders/{ticker} — query: include_ceased Get substantial shareholders (5%+ voting rights) for an NZX company from NZX disclosure notices. ~267 records across ~85 issuers. Shows entity name, entity type (individual/company/trust/fund), voting rights percentage, shares held, whether they are also a director/executive, disclosure dates, and threshold crossing history. Use for block holder analysis, activist investor tracking, M&A signal detection (accumulation patterns), and ownership concentration analysis. Complements get_shareholders (top-20 annual report data) with legally mandated real-time disclosures. Parameters: - ticker (string, required): NZX ticker symbol - include_ceased (string, optional): Set to "true" to include former substantial holders who dropped below 5% --- #### get_agm_resolutions GET /api/v1/agm-resolutions/{ticker} — query: year Get AGM resolution voting data for an NZX company. Shows resolutions, votes for/against/abstain, pass/fail status, support percentages. Use for governance and shareholder activism analysis. Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Filter by meeting year --- #### get_esg_data GET /api/v1/esg/{ticker} — query: year Get ESG (Environmental, Social, Governance) data for an NZX company. 255 emissions records, 760 diversity records, 270 safety records across NZX issuers. Includes emissions (scope 1/2/3, targets, verification), diversity (board/SLT/employee gender, Māori/Pasifika representation), safety (LTIFR/TRIFR, fatalities, FTE), and reporting standards (GRI/TCFD/SBTi). Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Filter by fiscal year --- #### get_kiwisaver_holdings GET /api/v1/kiwisaver-holdings/{ticker} — query: date Get KiwiSaver fund holdings in an NZX company. Shows which KiwiSaver funds hold shares, their market value, and percentage of fund. Data covers Dec 2018 - Sep 2022. Parameters: - ticker (string, required): NZX ticker symbol - date (string, optional): Specific quarter date (e.g. "2022-09-30") --- #### get_agm_speeches GET /api/v1/agm-speeches/{ticker} — query: year, role Get AGM speech analysis for an NZX company. Language Intelligence Score (LIS) measures communication quality. Includes sentiment, conviction, hedging, key themes. Use for governance quality and management communication analysis. Parameters: - ticker (string, required): NZX ticker symbol - year (string, optional): Year or range - role (string, optional): Filter by speaker role (e.g. "Chair", "CEO") --- #### get_performance GET /api/v1/performance/{ticker} Get stock performance metrics for an NZX company. Returns (1d to 5y), alpha vs NZX50, volatility, 52-week range, market cap. Use for performance comparison and pay-for-performance analysis. Parameters: - ticker (string, required): NZX ticker symbol --- #### get_technical_signals GET /api/v1/technical-signals/{ticker} Get technical analysis indicators for an NZX company. SMA-50/100/200, RSI-14, golden/death cross, distance from 52-week high/low, volume ratios. Use for trading signals, momentum analysis, and technical screening. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### screen_stocks GET /api/v1/screener — query: sector, q, preset, filter, sort, order, limit Screen NZX stocks across 87+ metrics — financials, valuation, technical signals, governance, insider activity. Supports smart presets (value, growth, quality, oversold, golden_cross, etc.), custom filters (e.g. filter=pe_ratio<15,rsi_14<30), sorting by any metric, and sector filtering. Use this for screening questions like "show me oversold stocks" or "value stocks with high dividends". 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 - filter (string, optional): Custom metric filters, comma-separated. Format: metric>value or metric3", "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) --- #### get_iod_designations GET /api/v1/iod-designations — query: designation, ticker, name, limit Get Institute of Directors (IoD) designated directors on NZX boards. Shows CFInstD (Chartered Fellow), CMInstD (Chartered Member), CDir (Chartered Director), and MInstD (Member) designations with current board seats. Can filter by designation level, ticker, or director name. Parameters: - designation (string, optional): Filter by IoD designation: "CFInstD", "CMInstD", "CDir", "MInstD" - ticker (string, optional): Filter by NZX ticker to see IoD directors at a specific company - name (string, optional): Search by director name - limit (number, optional): Max results (default 50) --- #### get_board_skills_matrix GET /api/v1/skills-matrix/{ticker} Get board skills matrix for an NZX company. Shows 12 skill categories (governance, financial, legal, strategy, technology, industry, risk, esg, international, people, commercial, government) with proficiency levels per director, gap analysis, and diversity score. Aligned with IoD NZ, ASX CGC, AICD frameworks. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_credit_ratings GET /api/v1/credit-ratings/{ticker} — query: year, agency, action, limit Get credit rating history for an NZX company. Shows S&P, Moody's, Fitch, AM Best ratings with upgrades, downgrades, and outlook changes. ~20 NZX companies have credit ratings. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "ANZ", "MEL", "SPK") - 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 --- #### get_ir_quality GET /api/v1/ir-quality/{ticker} Get IR Quality Score (IRQS) for an NZX company. Measures disclosure quality across 10 weighted dimensions: 5 core (51%): timeliness (filing speed vs NZX deadlines), completeness (data points disclosed in earnings, annual 70%/interim 30% weighting), readability (hedging/language clarity), frequency (announcements, presentations, AGMs), governance transparency (GRS + skills + ESG). 5 supplementary (49%): website quality, presentation quality, analyst coverage, guidance accuracy, segment reporting depth. 0-100 composite score grounded in OECD, CFA, S&P, NIRI, AIRA frameworks. 131 issuers scored. Ratings: Excellent (75+), Good (60-74), Adequate (40-59), Poor (20-39), Very Poor (<20). Includes trajectory (improving/stable/declining). v2.0 engine. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_peer_mentions GET /api/v1/peer-mentions/{ticker} — query: direction, relation Get peer mentions for an NZX company — which other companies reference it in their announcements, and which companies it references. Extracted from 62,000+ NZX documents. Shows network of business relationships, competitive dynamics, and sector interconnections. Includes context snippets. Each mention includes a relation_type (supplier, customer, partner, competitor, joint_venture, acquirer, subsidiary, licensee, advisor, shareholder, none) and relation_confidence (high, medium, low). Summary includes counts by relation type. Filter by relation type with the relation parameter. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - direction (string, optional): Filter direction: "mentions" (companies this ticker references), "mentioned_by" (companies referencing this ticker), or "both" (default) Options: mentions | mentioned_by | both. - relation (string, optional): Filter by relation type(s), comma-separated (e.g. "supplier,customer") --- #### get_board_gap_report GET /api/v1/board-gap-report/{ticker} Get a comprehensive Board Gap Intelligence Report for an NZX company. Includes board composition analysis, 12-category skills gap assessment, ideal next director profile, fee benchmarking vs sector, governance scores, risk flags, and sector benchmarks. PDF version available at /api/v1/board-gap-report/{ticker}/pdf. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_board_vacancies GET /api/v1/board-vacancies — query: source, sector, region, vacancy_id, limit Get current board vacancies scraped from Appoint Better Boards and IoD NZ. Filterable by source, sector, region, and remuneration type. Optionally returns candidate matches for a specific vacancy. 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) --- #### get_board_pipeline GET /api/v1/board-pipeline — query: sector, skill, limit Directors who have recently freed up board capacity — resignations, retirements, and reduced workloads in the last 12 months. Use to identify available director talent for board recruitment. Parameters: - sector (string, optional): Filter by sector (e.g. "Energy", "Healthcare", "Financial Services") - skill (string, optional): Filter by skill category (e.g. "governance", "financial", "technology") - limit (number, optional): Max results (default 20) --- #### get_ir_dashboard GET /api/v1/ir-dashboard/{ticker} Get a comprehensive Investor Relations dashboard for an NZX company. Combines 9 data sources: IR Quality Score, announcement sentiment monitoring (6mo trend), substantial shareholder composition (HHI concentration), insider trading activity (12mo with cluster detection), governance risk scores, earnings trajectory (revenue CAGR, profit trend), disclosure frequency analysis, and sector peer benchmarking. Built for IR teams, institutional investors, and analysts. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_ir_scorecard_compare GET /api/v1/ir-scorecard/compare — query: tickers Compare 2-5 NZX companies side-by-side across 7 IR quality dimensions: timeliness (filing speed), completeness (data point coverage), readability (language clarity), frequency (announcement cadence), governance (transparency scores), analyst coverage (broker analyst count), and IR accessibility (contact quality). Returns normalized 0-100 scores per dimension for each company. Ideal for competitive benchmarking. Parameters: - tickers (string, required): Comma-separated NZX ticker symbols, 2-5 companies (e.g. "FPH,CEN,SKL") --- #### get_narrative_tracker GET /api/v1/narrative-tracker/{ticker} Track how a company's management narrative evolves over time. Shows 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 in tone, guidance, topics, and hedging. Useful for detecting narrative pivots, credibility assessment, and earnings quality analysis. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_management_team GET /api/v1/management-team/{ticker} — query: role Get the management team (C-suite executives) for an NZX company. Returns current CEO, CFO, COO, CTO, and other senior executives with their roles, tenure, biographies, education, and profile links. 127 issuers covered, 508 current executives across 15 normalized roles. Filter by role (e.g. CEO, CFO). Includes profile data where linked to shared.people. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - role (string, optional): Filter by normalized role: CEO, CFO, COO, CTO, CIO, CLO, CPO, CMO, CRO, CDO, CS, GM, VP, MD, Other --- #### get_management_credibility GET /api/v1/management-credibility/{ticker} Get management credibility score for an NZX company. Composite 0-100 score measuring how trustworthy management forward guidance is, based on 4 factors: guidance accuracy (did they hit targets?), tone consistency (stable vs erratic), insider trading alignment (do insiders trade against guidance?), and guidance transparency (do they provide guidance at all?). Use when evaluating management quality or assessing whether to trust forward estimates. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_board_credentials GET /api/v1/director-qualifications/{ticker} Get board qualifications, credentials, universities, and credential gaps for an NZX company. Shows academic degrees (BCom, MBA, LLB), professional designations (CA, FCA, CFA), governance certifications (CFInstD, GAICD), and university backgrounds for all current directors. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_governance_scorecard GET /api/v1/governance-scorecard/{ticker} Get a per-company governance scorecard with RAG (red/amber/green) ratings across 15 policy areas aligned with NZSA governance policies and the NZX Corporate Governance Code. Covers: remuneration disclosure, CEO rem structure, board independence, audit independence, director tenure, board diversity, shareholder voting dissent, ESG, capital management, takeover vulnerability, management credibility, succession readiness, audit firm tenure, director share ownership. Returns overall score 0-100, individual policy assessments with scores and details. Use for governance due diligence, board briefings, or corporate governance benchmarking. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_board_health_score GET /api/v1/board-health-score/{ticker} Get board health score for an NZX company. Composite 0-100 governance metric measuring 5 factors: board composition (size, independence, gender diversity), effectiveness (attendance, skills coverage), stability (tenure distribution, turnover), experience (qualifications, memberships, international), and transparency (GRS, fee disclosure). Use when assessing overall board governance quality. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### simulate_investor_qa GET /api/v1/investor-qa/{ticker} Generate 10 tough investor questions for an NZX company with data-backed suggested responses. Simulates the hardest questions IR teams will face on investor calls or roadshows. Uses earnings intelligence, management credibility, peer comparison, insider activity, governance, and sentiment data. Categories: financial_performance, governance, strategy, capital_allocation, risk, valuation, insider_activity, guidance, peer_comparison, esg. Each question rated by difficulty (standard/tough/hostile) and risk level. ~$0.01-0.03/call. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_factor_grades GET /api/v1/factor-grades/{ticker} Get A-F factor grades for an NZX company across 6 dimensions: Value (PE/PB/EV vs sector), Growth (revenue/profit growth), Profitability (ROE/margins), Momentum (price returns), Dividends (yield/safety/payout), Governance (GRS score). Sector-relative percentile ranking. Composite grade included. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_earnings_quality GET /api/v1/earnings-quality/{ticker} Get earnings quality score for an NZX company. 0-100 composite score measuring how cash-backed and sustainable reported earnings are. 5 components: accruals ratio (net income vs operating cash flow burden), cash conversion (OCF/NI ratio), working capital efficiency (receivables/inventory trends vs revenue growth), earnings persistence (profitability consistency and volatility), capital intensity (capex vs depreciation reinvestment). Use when assessing whether profits are real cash or accrual-driven, evaluating dividend sustainability, or filtering fair value models. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_insider_clusters GET /api/v1/insider-clusters/{ticker} — query: months Detect insider conviction cluster patterns for an NZX company. Identifies coordinated insider trading: cluster buys (2+ directors buying within 14 days), cluster sells, sustained accumulation (single director buying repeatedly), and conviction reversals (direction switches). Returns alerts with severity and total value. Use when investigating whether insiders are acting with conviction. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - months (number, optional): Lookback period in months (default 6, max 24) --- #### get_credibility_momentum GET /api/v1/credibility-momentum/{ticker} Get management credibility momentum for an NZX company. Measures whether management credibility is improving or declining over time by comparing recent vs historical guidance accuracy, tone stability, insider alignment, and transparency trends. Returns momentum score (-100 to +100) and direction. Use when assessing whether management quality is on an upward or downward trajectory. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_dividend_cut_probability GET /api/v1/dividend-cut/{ticker} Get dividend cut probability for an NZX company. 9-factor model (0-95%) predicting likelihood of a dividend cut based on: earnings trajectory, payout ratio, dividend cover, capital raise recency, historical cut pattern, DPS trend, OCI divergence, share dilution, and macro environment. Use when evaluating dividend sustainability or screening for at-risk dividends. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_governance_deterioration GET /api/v1/governance-deterioration/{ticker} Get governance deterioration signal for an NZX company. 5-factor model (0-100) detecting weakening governance: GRS score level, board stability (recent departures/appointments), independence erosion, audit & risk flags, and board meeting attendance. Returns risk level, factors, and recent board events. Use when assessing whether a company's governance is in decline. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_oci_divergence GET /api/v1/oci-divergence/{ticker} Get OCI (Other Comprehensive Income) divergence signal for an NZX company. Analyses gap between reported net income and total comprehensive income to detect hidden FX/revaluation/hedging risks. 4-factor model: current magnitude, persistence, volatility, and trend. Returns risk score (0-100) and detailed metrics. Use when investigating whether headline earnings mask hidden losses. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_accounting_quality GET /api/v1/accounting-quality/{ticker} — query: year, limit Get accounting quality scores for an NZX company. Shows Beneish M-score (manipulation risk), Piotroski F-score (financial strength 0-9), Altman Z-score (bankruptcy risk), plus interest coverage and current ratio. 128 issuers scored. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - year (string, optional): Year or range (e.g. "2024" or "2020-2024") - limit (number, optional): Max results --- #### get_capital_raises GET /api/v1/capital-raises/{ticker} — query: year, type, buybacks, limit Get capital raise history for an NZX company. Includes placements, rights issues, SPPs, IPOs, bonds, buybacks, DRPs with amounts, pricing, and dilution. ~11,700 structured events across 131 issuers. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FBU", "RYM") - 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 --- #### get_revenue_segments GET /api/v1/segments/{ticker} — query: year, type, limit Get revenue segment breakdown for an NZX company. Returns operating, geographic, or product segment data including segment revenue, operating profit, and assets (all in NZD thousands). Use when asked about "revenue breakdown", "business segments", "divisions", "product groups", "geographic revenue", "segment analysis", or "what are the divisions of [company]". Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "SKC", "AIR", "FBU") - 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) --- #### get_takeovers GET /api/v1/takeovers/{ticker} — query: status, deal_type, year, limit Get M&A and takeover activity for an NZX company. Returns structured deal data: acquirer, target, offer price, total value, premium, acceptance %, status, timeline. Covers takeover offers, mergers, schemes of arrangement, compulsory acquisitions, and asset acquisitions. Use this when asked about "takeovers", "M&A", "acquisitions", "who is buying", "hostile bids", "scheme of arrangement", or deal activity for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "RBD", "RAK", "MCK") - 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) --- #### get_takeover_probability GET /api/v1/takeover-probability/{ticker} Get takeover probability score for an NZX company — 6-factor model (0-100) estimating acquisition likelihood based on undervaluation (PE below sector, P/B < 1, price vs 52w high), insider activity, board instability, governance weakness, capital structure, and historical M&A activity. Ratings: High (75-100), Elevated (50-74), Moderate (25-49), Low (0-24). Use when asked about "takeover target", "acquisition likelihood", "M&A probability", "could X be acquired". Parameters: - ticker (string, required): NZX ticker symbol (e.g. "RBD", "RAK", "NZM") --- #### get_market_signals GET /api/v1/signals — query: ticker, type, days, significance, sector, limit Get the Market Intelligence Feed — a unified stream of all NZX market events. Returns 13 signal types: insider trades, capital raises, dividends, earnings releases, AGM results, director changes, governance score changes, technical signals (golden/death cross, RSI extremes), credit rating changes, auditor changes, takeover/M&A activity, board events, and composite signals (multi-signal patterns like insider selling + earnings miss, director exodus, governance deterioration). Use this when asked "what happened on the NZX today/this week?", "any recent insider trades?", "golden crosses?", "credit rating changes?", "composite signals?", "market activity for AIR", or any question about recent NZX events. Parameters: - ticker (string, optional): Filter by company ticker (e.g. "AIR", "MEL") - 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 (e.g. "Energy", "Healthcare") - limit (number, optional): Max results (default 50) --- #### get_anomalies GET /api/v1/anomalies — query: ticker, category, severity, sector, days Get market anomaly detection results — an early warning system scanning all NZX companies for unusual patterns. Detects 16 anomaly types across 7 categories: insider trading clusters, insider exodus, conviction shifts, governance deterioration, director exodus, audit changes, dividend cut risk, capital raise patterns, earnings concerns, first-time risk language detection, technical breakdowns/breakouts, AGM revolts, active takeovers, sentiment-market disagreements, and buried risk detection. Use this when asked about "red flags", "warning signs", "anomalies", "governance concerns across the market", "which companies have problems", "sentiment disagreement", "buried risks", or market-wide risk assessment. Parameters: - ticker (string, optional): Filter by company ticker (e.g. "AIR", "MEL") - 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 (e.g. "Energy", "Healthcare") - days (number, optional): Number of days to look back (default 180) --- #### get_proxy_report GET /api/v1/proxy-report/{ticker} — query: year, meeting_id Get automated proxy advisory voting recommendations for a company's AGM resolutions. Evaluates 65+ rules across 8 categories (director elections, remuneration, auditor, capital management, constitution, related party, shareholder proposals, board structure). Returns FOR/AGAINST/REFER recommendation with reasoning for each resolution. Use this when asked about how to vote at an AGM, governance concerns for a company, or proxy advisory analysis. Parameters: - ticker (string, required): Company ticker symbol (e.g. "AIR", "MEL") - year (string, optional): Meeting year to analyze (e.g. "2025"). Default: latest meeting. --- #### get_annual_reports GET /api/v1/reports/{ticker} — query: year, type Get annual and interim report URLs for an NZX company. Shows report URLs, financial year, extraction status. Use this when asked about a company's annual reports, filings, or report history. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") - year (string, optional): Fiscal year or range (e.g. "2024" or "2020-2024") - type (string, optional): Filter: "annual" or "interim" --- #### read_annual_report_section GET /api/v1/report-content/{ticker} — query: year, section Read a specific section of an NZX company annual report. Returns the full markdown text of a section (e.g. "governance", "financial statements", "chairman's report"). If no section specified, returns table of contents with previews of each section. Use when asked to read, quote, or summarise a specific part of an annual report. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") - year (string, optional): Financial year (e.g. "2025"). Defaults to latest. - section (string, optional): Section name to read (e.g. "governance", "financial statements", "risk management"). Fuzzy matched. Omit to get TOC. --- #### get_director_due_diligence GET /api/v1/director-report/{slug} Get a comprehensive due diligence report for any NZX director. Returns all board positions (current + historical), overboarding assessment, remuneration across all boards, AGM election voting record, insider trading activity, governance contribution (GRS scores of companies served), stock performance during tenure, and risk flags. Use this when asked about a director's governance track record, suitability for board appointment, or comprehensive background. Parameters: - slug (string, required): Director slug (e.g. "joan-withers", "mark-cross"). Use get_directors with search param to find the slug first. --- #### get_kyc_screening GET /api/v1/kyc-screening/{slug} Run automated KYC/AML screening on an NZX director. Cross-references 12 risk databases: regulatory actions (FMA/ComCom), court cases, professional disciplinary, prohibited directors register, MBIE insolvency register (bankruptcies/NAPs), Companies Office directorship history (failed companies), ICIJ offshore leaks, OFAC/UN/EU sanctions lists, adverse media (NZ news), political donors, MP interest entities, and company failure summary. Returns risk score (0-100), risk rating (Low/Medium/High/Critical), sanctions match status, PEP status, adverse media mentions, detailed per-database screening hits, and risk breakdown by 8 categories. Active bankruptcy or confirmed sanctions match = auto-Critical. Corporate tier only. Parameters: - slug (string, required): Director slug (e.g. "joan-withers"). Use get_directors with search param to find the slug first. --- #### get_board_composition_report GET /api/v1/board-report/{ticker} Get a comprehensive board composition analytics report for an NZX company. Analyzes independence, diversity, tenure, skills matrix, attendance, remuneration, succession risk, turnover, and peer benchmarks. Returns risk flags and comparison against NZX Code and sector averages. Use this when asked about board composition, governance quality, board diversity, succession planning, or nomination committee analysis. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### search_keyword_trends GET /api/v1/keyword-trends — query: keyword, keywords, ticker Search any keyword or phrase across 64,000+ NZX company announcements and see how often it appears over time. Shows frequency by year (with adoption rate and YoY growth), sector, top companies (with first mention date), and overall first mention. Use for "when did NZX companies start talking about AI?", "which sector mentions climate risk most?", "how often does [company] mention restructuring?", "compare AI vs climate mentions". Supports multi-keyword comparison and ticker-specific filtering. Parameters: - keyword (string, optional): Single keyword or phrase to search (e.g. "artificial intelligence", "restructuring", "net zero") - keywords (string, optional): Comma-separated keywords for comparison (e.g. "ai,climate,esg"). Max 5. Use instead of keyword param. - ticker (string, optional): Filter to a specific NZX company ticker (e.g. "AIR", "FPH") --- #### get_risk_language GET /api/v1/risk-language/{ticker} Get pre-computed risk language scores for an NZX company. Scans 64,000+ announcements for 8 risk categories: going_concern, covenant, impairment, litigation, restructuring, liquidity, regulatory, force_majeure. Returns total mentions, 12-month trend (increasing/decreasing/stable), category breakdown, critical flags, first-time detections (categories appearing for the first time — a key early warning signal), and yearly trend. Use when asked about risk factors, going concern warnings, covenant issues, litigation exposure, first-time risk language, or regulatory risk for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### list_stewardship_reports GET /api/v1/stewardship-reports List FMA-compliant stewardship/voting-record reports for the current user. Returns report summaries with vote counts, compliance rates, and period dates. Use when asked about stewardship reports, voting records, FMA compliance reports, or fund manager voting history. Corporate tier required. --- #### get_stewardship_report GET /api/v1/stewardship-reports/{id} Get full detail for a specific stewardship report by ID, including per-company resolution analysis, vote recommendations, and the policy used. Use when asked about a specific voting report's details. Corporate tier required. Parameters: - id (number, required): Stewardship report ID --- #### list_voting_policies GET /api/v1/voting-policies List all custom voting policies for the current user. Each policy defines threshold overrides for the proxy advisory engine (board independence, remuneration caps, tenure limits, gender diversity, etc.). Use when asked about voting policies, proxy policy settings, or governance thresholds. Corporate tier required. --- #### list_engagement_log GET /api/v1/engagement-log — query: ticker List stewardship engagement log entries for a company. Returns conversations, contacts, topics, outcomes, escalation status, and linked voting decisions. Use when asked about engagement history, stewardship conversations, NZ Stewardship Code Principle 4, or how a company was engaged before voting. Corporate tier required. Parameters: - ticker (string, required): NZX ticker symbol (e.g. AIR, FPH) --- #### get_vote_history GET /api/v1/vote-history — query: ticker, year, dissent_only Get historical voting analytics showing how different fund managers voted on the same NZX resolutions. Cross-fund comparison with dissent rates, management alignment, and vote change tracking. Use when asked about historical voting patterns, fund voting comparison, dissent analysis, or how funds voted on a company. Corporate tier required. Parameters: - ticker (string, optional): NZX ticker symbol to filter by (optional) - year (string, optional): Year to filter by, e.g. 2025 (optional) - dissent_only (boolean, optional): If true, only return resolutions where funds disagreed or voted against management --- #### list_alert_subscriptions GET /api/v1/alerts/subscriptions List all alert subscriptions for the authenticated user. Each subscription filters market signals and anomalies by tickers, sectors, 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), anomaly categories, and severity levels — then delivers via webhook, email, Slack, or Teams. Use when asked about alert subscriptions, webhook alerts, or notification settings. Corporate tier required. --- #### get_board_briefing GET /api/v1/board-briefing/{ticker} Get a comprehensive board meeting preparation briefing for a company. Includes governance scores, insider activity, announcements with sentiment, dividend analysis, financial health, peer comparison, AGM status, and board changes. Parameters: - ticker (string, required): NZX ticker symbol --- #### get_research_briefing GET /api/v1/research/{ticker} — query: template, focus Generate a comprehensive investment research briefing for a company. Assembles 15+ data sources and produces AI-synthesized narrative with executive summary, key strengths, risks, and outlook. Supports 5 templates: general, investment_thesis, due_diligence, board_meeting, short_thesis. Use short_thesis for bear case analysis with 6-18 month horizon. Parameters: - ticker (string, required): NZX ticker symbol - template (string, optional): Research template: general (default), investment_thesis, due_diligence, board_meeting, or short_thesis (bear case) Options: general | investment_thesis | due_diligence | board_meeting | short_thesis. - focus (string, optional): Comma-separated focus areas, e.g. "dividends,governance,insider activity" --- #### get_deep_research GET /api/v1/deep-research/{ticker} — query: template, question Run a comprehensive 5-phase agentic deep research pipeline on a company. Gathers fundamentals, governance, market position, dividends, and recent events using 20+ data tools, then synthesizes into a McKinsey-style structured investment report. Takes 30-90 seconds. Use for deep-dive, multi-faceted research requests where the user wants a thorough analysis. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "SPK") - template (string, optional): Research template: general (default), investment_thesis, due_diligence, board_meeting, or earnings_preview Options: general | investment_thesis | due_diligence | board_meeting | earnings_preview. - question (string, optional): Optional specific question to focus the research on --- #### get_earnings_preview GET /api/v1/deep-research/{ticker} — query: question, template Generate a pre-reporting season earnings preview report for an NZX company. Analyses consensus vs price (upside/downside %), guidance accuracy history (last 3 years), management tone trends, insider trading alignment, earnings surprise probability (8-factor model), management credibility score, key financial metrics to watch, and a "what to watch" summary. Uses the deep research pipeline with the earnings_preview template. Takes 30-90 seconds. Use when a user asks about upcoming results, earnings expectations, or wants to prepare for a reporting season. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "SPK") - question (string, optional): Optional specific question to focus the earnings preview on --- #### get_announcement_sentiment GET /api/v1/sentiment/{ticker} — query: sentiment, hedging, from, to, limit Get AI-scored sentiment analysis of NZX announcements for a company. Returns per-announcement sentiment scores (-1 to +1), confidence, hedging level, buried risks, key topics, and guidance direction. Includes company-level summary with average score and sentiment breakdown. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "SPK") - sentiment (string, optional): Filter by sentiment: 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) --- #### get_director_conflicts GET /api/v1/director-conflicts/{ticker} Detect conflicts of interest for directors of an NZX company. Returns cross-directorships (directors on multiple NZX boards), overboarding risk (too many positions), related entity overlaps (directors sharing roles at same charities/public sector), and cross-company insider trading flags. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_fund_votes GET /api/v1/fund-votes/{ticker} — query: fund_manager, year, vote, limit Get actual voting records from NZ fund managers (Harbour, Devon, Mint, Fisher, NZ Super) for a specific company. Shows how institutional investors voted on AGM resolutions — FOR, AGAINST, or ABSTAIN. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "CHI", "FBU", "AIR") - 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) --- #### get_regulatory_actions GET /api/v1/regulatory-actions/{ticker} Get regulatory enforcement actions for an NZX company from FMA, Commerce Commission, NZX, and other regulators. Returns enforcement history, penalties, severity, prohibited director flags. Use when asked about regulatory risk, enforcement history, FMA actions, fines, or compliance issues for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_prohibited_directors GET /api/v1/prohibited-directors Get the full list of prohibited/banned directors from the Companies Office register, including any matches to current NZX directors. Use when asked about prohibited directors, banned directors, disqualified persons, or director fitness checks. --- #### get_litigation_history GET /api/v1/litigation/{ticker} Get court litigation history for an NZX company. Returns cases from High Court, Court of Appeal, and Supreme Court where the company or its directors are parties. Includes case type, outcome, dates, and damages. Use when asked about lawsuits, court cases, legal proceedings, or litigation risk for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") --- #### get_director_history GET /api/v1/director-history/{slug} Get a director's full company history and failure rate. Shows all NZX board positions, biographical company mentions, and associations with failed companies (liquidations, receiverships). Includes failure rate percentage and risk level. Use when asked about a director's track record, past boards, failure rate, or corporate history. Parameters: - slug (string, required): Director slug (URL-friendly name, e.g. "rob-campbell") --- #### get_director_risk GET /api/v1/director-risk/{slug} Get composite risk score (0-100) for an NZX director. Aggregates failure rate, litigation, regulatory actions, professional disciplinary, offshore exposure, and overboarding into a single weighted score. Use when assessing director suitability, governance risk, or board appointment due diligence. Parameters: - slug (string, required): Director slug (e.g. "rob-campbell"). Use get_directors with search param to find the slug first. --- #### get_director_network GET /api/v1/director-network — query: ticker, director, include_historical Analyze director network patterns — cross-directorships, board interlocks, shared entities. Three modes: (1) company mode (ticker param) shows network for a company's board, (2) director mode (director param) shows a person's full network including all shared boards and connected directors, (3) network mode (no params) shows NZX-wide cross-directorship map with most connected directors. Use when asked about "director network", "who is connected to", "board interlocks", "cross-directorships", "overlapping boards", "shared directors", or "who sits on multiple boards". Parameters: - ticker (string, optional): NZX ticker to analyze board network for (e.g. "AIR"). Omit for director or network mode. - director (string, optional): Director slug or name to find network around (e.g. "joan-withers" or "Joan Withers"). Omit for company or network mode. - include_historical (boolean, optional): Include historical positions, not just current. Default: false. --- #### get_agency_charity_funding GET /api/v1/agency-charity-funding — query: agency, charity, limit Cross-platform agency↔charity funding graph. Combines two sources: (1) major contracts disclosed in charity annual reports (annualised values, expiry dates) and (2) GETS (Government Electronic Tenders Service) awarded contracts where the supplier is a registered charity. Three modes: (a) pass `agency` to list charities funded by that NZ govt agency, (b) pass `charity` to list agencies funding that charity, (c) pass neither for a platform-wide summary with top 25 of each. Use for questions like "which charities does MSD fund", "who funds Women's Refuge", "top charities by government funding", or "government funding expiry risk for NZ charities". Values: AR = annualised, GETS = awarded totals. Parameters: - agency (string, optional): Agency slug or name substring (e.g. "ministry-of-social-development", "MSD", "Te Whatu Ora"). Mutually exclusive with `charity`. - charity (string, optional): Charity slug or name substring (e.g. "womens-refuge", "Salvation Army"). Mutually exclusive with `agency`. - limit (number, optional): Max rows returned in top_charities / top_agencies lists (default 25, max 200). --- #### get_entity_graph GET /api/v1/entity-graph/{identifier} — query: type, depth Get the cross-platform entity relationship graph for a person or company. Returns nodes (people, companies, charities, iwi, agencies) and edges (board roles, executive roles, interests, donations, ownership) across all 4 Pangaea platforms. Use for questions about a person's full governance footprint, cross-platform connections, or company relationship maps. Pass a person slug for people, a ticker for companies. Parameters: - identifier (string, required): Person slug (e.g. "joan-withers") or NZX ticker (e.g. "AIR") - type (string, optional): Entity type: "person", "company", or "auto" (default: auto-detect) - depth (number, optional): Relationship depth: 1 (direct connections) or 2 (includes co-directors/other boards). Default: 1. --- #### get_alpha_factors GET /api/v1/alpha-factors/{ticker} Get Qlib-inspired alpha factor scores for an NZX company. Returns composite alpha score (0-100) across 1M/3M/12M horizons, factor exposures (percentile rank per significant factor), top contributing factors, headwind factors, and rating. Based on IC analysis of 36 fundamental/technical/governance metrics. Use for quantitative analysis, factor exposure, alpha signals, or stock scoring. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_audit_history GET /api/v1/audit-history/{ticker} Get audit opinion history and red flags for an NZX company. Returns auditor name/firm, opinion type (unmodified/qualified/adverse/disclaimer), going concern warnings, emphasis of matter, key audit matters, audit/non-audit fees, and computed risk signals. Use when asked about audit risk, auditor, going concern, audit opinion, audit fees, or auditor independence for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_auditor_red_flags GET /api/v1/audit-history/{ticker} Get auditor red flags and risk signals for an NZX company. Returns qualified/adverse audit opinions, going concern warnings, auditor tenure concerns (>10 years), non-audit fee independence issues (ratio >1.0), key audit matters count, recent auditor changes, and composite risk level (critical/high/elevated/moderate/low). Use when asked about audit red flags, auditor risk, auditor independence, going concern, or audit quality for a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_professional_disciplinary GET /api/v1/professional-disciplinary/{ticker} Get professional body disciplinary records for directors of an NZX company. Sources: CA ANZ (accountants), NZ Law Society (lawyers), Medical Council (doctors), Engineering NZ (engineers). Returns action type, severity, outcome, and match confidence. Use when asked about professional misconduct, disciplinary history, professional body sanctions, or director professional standing. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_offshore_exposure GET /api/v1/offshore-exposure/{ticker} Get ICIJ Offshore Leaks Database matches for directors and entities of an NZX company. Covers Panama Papers, Pandora Papers, Paradise Papers, Bahamas Leaks. Returns match scores and review status. Use when asked about offshore exposure, Panama Papers, Pandora Papers, offshore entities, shell companies, or tax haven connections for a company or its directors. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_select_committee_activity GET /api/v1/select-committee/{ticker} Get NZ Parliament select committee activity for an NZX company. Returns committee reports mentioning the company (annual reviews, inquiries, bills) and bill submissions made by the company. Covers all parliaments from 1990 to present. Use when asked about parliamentary scrutiny, select committees, government oversight, SOE annual reviews, or corporate submissions to parliament. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "MEL", "SPK") --- #### get_watchlists GET /api/v1/watchlist Get the authenticated user's watchlists. Returns list of watchlists with names and tickers. Use when asked about their watchlist, tracked companies, or which companies they follow. --- #### get_keyword_alerts GET /api/v1/keyword-alerts — query: include_matches Get the authenticated user's keyword alerts and recent matches. Returns alert configurations and announcements that matched their keywords. Use when asked about their alerts, keyword notifications, or what announcements matched their keywords. Parameters: - include_matches (boolean, optional): Include recent alert matches (default false) --- #### get_morning_brief GET /api/v1/morning-brief — query: date, generate, days Get or generate a morning brief for the authenticated user's watchlist companies. Returns overnight announcements, insider trades, price moves, dividends, and governance changes. Use when asked for a morning brief, daily digest, overnight summary, or what happened with their watched 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) --- #### get_political_connections GET /api/v1/political-connections/{ticker} Get political connections for an NZX company. Returns MP interests (gifts, hospitality, shareholdings, travel mentioning this company), political donors linked to the company or its directors, and party donation records. Data from the NZ Parliamentary Register of Interests and Electoral Commission. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "SKC", "AIR", "SAN") --- #### get_councillor_interests GET /api/v1/councillor-interests/{council_slug} — query: term, include Get pecuniary interests declared by councillors on a specific NZ council. Shows financial interests including company directorships, shareholdings, trusts, property, employment, gifts, hospitality, and organisation memberships. Data from council interest registers under the Local Authorities (Members' Interests) Act 1968. Use when asked about councillor conflicts of interest, council member business interests, or local government transparency. Parameters: - council_slug (string, required): Council slug (e.g. "wellington-city-council", "auckland-council", "christchurch-city-council") - term (string, optional): Filter by council term (e.g. "2025-2028"). Omit for all terms. - include (string, optional): Comma-separated extras: "entities" (top entities), "summary" (aggregate stats) --- #### get_news_sentiment GET /api/v1/news-sentiment/{ticker} — query: days, source Get AI-scored news sentiment for an NZX company from NZ financial media (Interest.co.nz, NZ Herald, RNZ, NBR, Stuff). Returns 7d/30d averages, sentiment distribution, top topics, and recent scored articles. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "SPK", "FBU") - days (number, optional): Number of days to look back (default 30) - source (string, optional): Filter by source: "interest", "nzherald", "rnz", "nbr", "stuff" --- #### get_broker_coverage GET /api/v1/broker-coverage/{ticker} — query: include Get analyst/broker coverage for an NZX company. Shows which brokers and analysts cover the stock, their latest ratings (buy/hold/sell), price targets, earnings forecasts, and recommendation distribution. Includes consensus summary with mean/median target prices. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") - include (string, optional): Comma-separated sections: ratings, forecasts, reports, summary, all (default: ratings,summary) --- #### get_consensus_estimates GET /api/v1/estimates/{ticker} Get unified analyst consensus estimates for an NZX company. Combines Yahoo Finance consensus (target prices, buy/hold/sell), company guidance (revenue/NPAT/EBITDA ranges with accuracy history), individual broker ratings and forecasts, earnings surprise probability, and valuation context. The most complete view of market expectations for any NZX stock. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_deal_advisers GET /api/v1/deal-advisers/{ticker} — query: deal_type, role Get professional advisers (law firms, investment banks, valuers) who advised on capital raises and takeovers for an NZX company. Shows which firms acted as legal counsel, underwriter, lead manager, independent adviser, or valuer on each deal. Includes deal details (amount, type, date) and adviser roles. Use for deal intelligence, adviser league tables, or capital markets analysis. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "CEN") - 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. --- #### get_company_pager GET /api/v1/company-pager/{TICKER} Generate a one-page company snapshot with key financial metrics (revenue, profit, EBITDA, margins, ratios), governance score (GRS, board composition, independence), dividend data (DPS, yield, payout ratio, streak), insider activity (90-day trades, net direction), risk flags, and recent announcements. Use for quick due diligence, adviser client meetings, or company overview summaries. Also available as a branded PDF at /api/v1/company-pager/{ticker}/pdf. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL") --- #### get_deal_insider_signals GET /api/v1/deal-insider-signals/{ticker} — query: days, deal_type Detect insider trading patterns before capital raises and takeovers. Cross-references director share transactions (9,453 records) with deal announcements to flag pre-deal buying or selling within 30/60/90 days. Returns signal type (buy/sell/mixed), severity (critical/high/medium/low), volume anomaly vs 12-month average, and individual director activity. Use to detect insider confidence signals, potential information leakage, or dilution concerns ahead of deals. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "MEL"), or "all" for market-wide scan - days (number, optional): Lookback window in days before deal (30, 60, or 90). Default 90. - deal_type (string, optional): Filter by deal type: capital_raise or takeover --- #### get_deal_prediction GET /api/v1/deal-prediction/{ticker} Score an NZX company 0-100 for likelihood of capital raise in next 12 months. 8-factor model: raise frequency, recency, cash position, debt pressure, insider buying, dividend stress, adviser appointments, capex needs. Use ticker "all" for market-wide rankings. Identifies companies most likely to need capital. Parameters: - ticker (string, required): NZX ticker symbol or "all" for market-wide --- #### get_adviser_market_share GET /api/v1/adviser-market-share NZX deal adviser league tables — annual and quarterly market share rankings by deal count and value. Shows which law firms, investment banks, and accounting firms dominate NZX capital markets. Includes sector specialization and historical trends. --- #### get_deal_conflicts GET /api/v1/deal-conflicts/{ticker} Detect potential conflicts of interest in NZX capital markets deals. Cross-references deal advisers with director appointments (cross-board conflicts), MP interests, auditor independence (same firm audits and advises), and councillor declarations. Use ticker "all" for market-wide scan. Parameters: - ticker (string, required): NZX ticker symbol or "all" for market-wide --- #### get_macro_regime GET /api/v1/macro-regime Get the current NZ macroeconomic regime: RBNZ OCR rate and cycle direction, GDP growth, CPI inflation, unemployment rate, NZD exchange rates, US Fed Funds, US 10Y Treasury. Use this to provide macro context for investment analysis. --- #### get_macro_exposure GET /api/v1/macro-exposure/{ticker} Get a company's macro sensitivity profile: OCR sensitivity (high/moderate/low based on debt and interest cover), FX exposure (based on revenue segments), cyclicality, and composite macro risk score (0-100). Explains how macro changes affect this specific company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "RYM", "FPH", "AIR") --- #### get_macro_history GET /api/v1/macro-indicators — query: code, category, from, to Get historical time series for a macro indicator. Codes: 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. Or filter by category: growth, inflation, employment, housing, global, fx, monetary_policy. Parameters: - code (string, optional): Indicator code (e.g. "RBNZ_OCR", "NZ_GDP_QOQ") - 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) --- #### get_beneficial_ownership GET /api/v1/beneficial-ownership/{ticker} Get reconstructed beneficial ownership for an NZX issuer. Cross-references top-20 shareholder registers with fund manager holdings and custodian mappings to identify who is behind nominee/custodian entries. Returns direct holders, nominee breakdowns with identified fund managers, fund holdings, and substantial holders. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "SPK", "AIR") --- #### get_substantial_holder_notices GET /api/v1/substantial-holders/{ticker}/notices — query: holder, direction, limit Get substantial holder notices (SPH) for an NZX company. 9,704 classified SHINTR announcements with holder name, type, percentage, direction (increase/decrease/initial/ceased), and fund manager cross-reference. Shows real-time ownership changes between semi-annual filings. Use for M&A tracking, activist detection, institutional ownership changes. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - 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) --- #### get_substantial_holder_changes GET /api/v1/substantial-holders/{ticker}/changes — query: type, days Get substantial holder ownership change events for an NZX company. Tracks increases, decreases, initial disclosures, and ceased holdings from substantial holder filings. Shows previous vs current percentage, share counts, holder type, and disclosure dates. Use for monitoring institutional ownership shifts, activist accumulation, and divestment patterns. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - type (string, optional): Filter by change type: initial, increase, decrease, ceased, crossed_10, crossed_20 - days (number, optional): Lookback period in days (default 365) --- #### get_corporate_giving GET /api/v1/corporate-giving/{ticker} Get corporate donations, sponsorships, and community investment for an NZX company. Shows recipients, amounts, donation types (cash/sponsorship/community_investment/grant/in-kind), foundation name, and total community investment. Cross-linked to registered charities where possible. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "SPK", "AIR", "GMT") --- #### get_corporate_relationships GET /api/v1/corporate-relationships/{ticker} Get all professional service relationships for an NZX company — auditors, law firms, share registrars, and bankers. Returns current and historical relationships, audit fee data, and companies sharing the same advisers. Useful for understanding corporate dependencies and hidden connections. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SKC") --- #### get_property_portfolio GET /api/v1/property-portfolio/{ticker} Get property portfolio data for an NZX-listed REIT or property company. Returns individual properties with book values, cap rates, WALE, occupancy, tenants, locations, climate risk scores, plus portfolio summary, type/regional breakdowns, and development pipeline. Works for: KPG, ARG, PFI, VHP, IPL, SPG, CDI, GMT, PCT, APL. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "KPG", "ARG", "GMT", "VHP") --- #### get_hiring_intelligence GET /api/v1/hiring-intelligence/{ticker} — query: category, location Get Seek NZ hiring intelligence for an NZX company. Shows active job listings, hiring velocity (30d/90d), role breakdown by category, salary ranges, location distribution, and sector comparison. Alternative data — hiring acceleration is a leading indicator for company growth or restructuring. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "SPK") - category (string, optional): Filter by job category (e.g. "Engineering", "Finance") --- #### get_property_climate_risk GET /api/v1/property-portfolio/{ticker} Get climate and natural hazard risk analysis for an NZX property company portfolio. Returns per-property risk scores (0-100 composite), seismic zones (NZS 1170.5, 1-4), flood risk, liquefaction risk, coastal proximity, and sea level rise exposure. Includes portfolio-level averages, high-risk property count, and highest seismic zone. Based on published NZ government hazard data (NZS 1170.5, GNS Science, MfE, NIWA). Works for: KPG, ARG, PFI, VHP, IPL, SPG, CDI, GMT, PCT, APL. Parameters: - ticker (string, required): NZX ticker symbol of a property company (e.g. "KPG", "GMT", "VHP") --- #### get_analyst_consensus GET /api/v1/broker-coverage/{ticker} — query: include Get analyst consensus data for an NZX company — consensus rating (buy/hold/sell), analyst count, target prices (mean/median/high/low), buy/hold/sell breakdown, and list of covering brokers. Returns the latest consensus snapshot. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "SPK", "FPH") --- #### get_people_profile GET /api/v1/people/{slug}/profile Get a comprehensive cross-platform intelligence report for a person. Covers NZX board roles, charity trusteeships, public sector appointments, iwi roles, MP status, skills matrix, remuneration history, executive compensation, insider trades, governance scores, conflicts, and political connections. Uses the person slug (e.g. "john-smith"). $0 cost. Parameters: - slug (string, required): Person slug from shared.people (e.g. "john-smith", "jane-doe") --- #### simulate_event GET /api/v1/simulate-event/{ticker} — query: event_type, ocr_change, customer_name Simulate a hypothetical event on an NZX company and estimate its impact on share price, revenue, governance, and stakeholders. Event types: ceo_departure, ocr_change, major_customer_loss, dividend_cut, earnings_miss, acquisition, regulatory_action, director_resignation, capital_raise, credit_downgrade. Uses actual company financial data and NZX historical precedents. Pure computation, $0 cost. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH", "SPK") - event_type (string, required): Type of event to simulate: 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 events: basis point change (e.g. -25 for a 25bp cut, +50 for a 50bp hike) - customer_name (string, optional): For major_customer_loss events: name of the customer being lost --- #### analyse_ir_draft POST /api/v1/ir-rehearsal/{ticker} Analyse a draft NZX announcement before publication. Scans for FMA compliance risks, defamation language, superlatives, negative market trigger words, forward-looking statement count, hedging excess, and buried risks. Predicts likely market sentiment, estimates media pickup probability, generates analyst follow-up questions, detects corporate buzzwords, and assesses readability. Uses NZXplorer historical NZX language and sentiment data. POST endpoint — requires draft_text in body. $0 cost (pure regex/heuristic). Useful for IR teams, company secretaries, and communications professionals. Parameters: - ticker (string, required): NZX ticker symbol for the company publishing the announcement (e.g. "AIR", "FPH") - draft_text (string, required): The draft announcement text to analyse (50-50,000 characters) --- #### predict_agm_outcome GET /api/v1/agm-predictor/{ticker} — query: year, resolution_type Predict the outcome of AGM resolutions for an NZX company. Uses historical voting patterns, fund manager voting records (NZ Super, Fisher, Devon, Harbour, Milford), ownership composition, and governance context. Returns predicted support %, swing voters, risk factors, and historical comparisons. Pure computation, $0 cost. Useful for proxy advisors, companies planning contentious resolutions, and institutional investors. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") - year (number, optional): Optional meeting year to predict (defaults to latest) - resolution_type (string, optional): Optional resolution category filter: director_election, remuneration, auditor, capital_management, constitution, related_party, shareholder_proposal --- #### analyse_narrative_risk POST /api/v1/narrative-risk/{ticker} Multi-stakeholder narrative risk simulation for a draft NZX announcement. Predicts how institutions, retail investors, media, analysts, and regulators will react. Returns composite risk score (0-100), stakeholder reactions with severity and likely actions, signal conflicts, recommended IR actions, and reaction timeline. Uses IR Rehearsal engine + company context + optional Claude Haiku simulation (~$0.10). POST endpoint — requires draft_text. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") - draft_text (string, required): Draft announcement text to analyse (50-50,000 chars) --- #### get_first_time_chairs GET /api/v1/first-time-chairs — query: recent_only, sector, limit Get NZX directors serving as board chair for the first time. Shows recent appointments, prior board experience, governance risk scores. Useful for governance transition analysis and board succession planning. 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) --- #### search_board_candidates GET /api/v1/board-search — query: skills, sector, gender, max_boards, available_only, exclude_ticker, experience_type, keyword, min_fee, max_fee, limit Search across 2,000+ NZX directors AND 500+ executives for board/leadership candidates. Filter by skills (12 categories), sector, gender, board load, experience type (board/executive/both), fee range, and keyword (searches bios & career history). Returns ranked candidates with match scores, cross-platform experience (charity/iwi/public sector roles), career highlights, and executive roles. IoD-equivalent director search. 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 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) --- #### get_company_changes GET /api/v1/company-changes/{ticker} — query: days Get recent material changes for a company based on AI-extracted announcement data. Shows revenue, profit, dividend, and guidance changes detected from recent filings. Compares key financial figures across consecutive announcement extractions to surface meaningful deltas. Parameters: - ticker (string, required): NZX ticker symbol (e.g., "FPH", "AIR") - days (number, optional): Lookback period in days (default 30, max 365) --- #### get_agent_events GET /api/v1/agent-events — query: tickers, types, days, severity, limit Get enriched market events with full context for AI agent consumption. Each event includes company governance scores, insider conviction, dividend safety, financial/technical context, compound directives (GOVERNANCE_ALARM, DIVIDEND_RISK, INSIDER_CONVICTION, etc.), and machine-readable suggested actions. Use this instead of multiple individual lookups when you need to understand what is happening at a company. Parameters: - tickers (string, optional): Comma-separated NZX tickers (e.g., "AIR,FPH") - types (string, optional): Comma-separated signal/directive types (e.g., "insider_trade,GOVERNANCE_ALARM") - days (number, optional): Lookback days (default 30) - severity (string, optional): Minimum severity: low, medium, high, critical - limit (number, optional): Max results (default 50) --- #### get_earnings_surprise GET /api/v1/earnings-surprise/{ticker} Get earnings surprise probability for a company — predicts beat/miss likelihood using 9-factor model calibrated from 716-event backtest (guidance accuracy, tone consistency, analyst consensus, historical beat/miss pattern, insider alignment, transparency, volatility, capital stress, forward-looking density). Directional accuracy: 53% upside, 45% downside. Returns surprise_probability (0-100%), direction (upside/downside/inline), risk level, and factor breakdown. Parameters: - ticker (string, required): NZX ticker symbol (e.g., "FPH", "AIR") --- #### get_alpha_score GET /api/v1/alpha-score/{ticker} Get composite alpha score (0-100) for an NZX company combining 5 proprietary signal dimensions: governance (GRS + resignation clusters), insider conviction (buy/sell clusters), management credibility (tone analysis), financial quality (F-Score/Z-Score), and dividend sustainability. Each signal has been backtested on 10 years of NZX data. Returns score, rating (Strong Alpha/Moderate Alpha/Neutral/Moderate Risk/High Risk), component breakdown, and active signal flags with validated alpha spreads. Parameters: - ticker (string, required): NZX ticker symbol (e.g., "FPH", "AIR") --- #### get_fair_value GET /api/v1/fair-value/{ticker} — query: discount_rate, terminal_growth Get estimated fair value for a company using 3 valuation models: DCF (discounted cash flow), Dividend Discount Model (Gordon Growth), and EV/EBITDA relative valuation. Returns composite fair value per share, price-to-fair-value ratio, individual model outputs, confidence level, and methodology notes. Users can optionally adjust discount rate and terminal growth rate. NOTE: This is an automated estimate using standard financial models, NOT a target price or investment recommendation. Parameters: - ticker (string, required): NZX ticker symbol (e.g., "FPH", "AIR") - discount_rate (number, optional): Discount rate / WACC (default 0.10 = 10%) - terminal_growth (number, optional): Terminal growth rate (default 0.025 = 2.5%) --- #### get_committee_chairs GET /api/v1/committee-chairs — query: committee, ticker, sector, limit Get board committee membership data — chairs, committee types, and composition across NZX companies. Use when user asks about audit committees, remuneration committees, committee chairs, or board committee structure. Parameters: - committee (string, optional): Filter by committee type (e.g., "Audit", "Risk", "Remuneration", "Nomination") - ticker (string, optional): Filter by company ticker (e.g., "AIR") - sector (string, optional): Filter by sector - limit (number, optional): Max results (default 50, max 200) --- #### get_network_intelligence GET /api/v1/network-intelligence — query: mode, from, to, current_only, cross_platform, limit Analyze the NZX director network — find connection paths between people, identify power brokers by centrality, detect governance communities. Use when user asks "how is Director A connected to Director B?", "who are the most influential directors?", "which directors form clusters?", or "governance network analysis". 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) --- #### get_remuneration_benchmarks GET /api/v1/remuneration-benchmarks — query: role, sector, market_cap, board_size, year, include_trend Get NZX director compensation benchmarks — median, P25/P75 board fees by sector, market cap, and role. Use when user asks "what does a chair earn?", "director fee benchmarks", "compensation comparison", "how much do NZX directors get paid?", "remuneration benchmarking". 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" --- #### search_skills_taxonomy GET /api/v1/skill-search — query: q, mode, limit Search the ESCO-aligned skills taxonomy to find matching director skill categories. Use when user asks "find directors with cybersecurity skills", "who has M&A experience?", "Te Tiriti governance expertise", or any skill-related director search. Maps free-text queries to NZXplorer's 12 skill categories with 68 sub-skills. 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) --- #### check_insolvency_status GET /api/v1/insolvency/{slug} Check insolvency/bankruptcy history for any person in the NZXplorer database. Queries the MBIE Insolvency Register for bankruptcy, no-asset procedures, and summary instalment orders. Returns TTL-filtered records per MBIE Agreement cl 4.5-4.6. Use when asked about a person's insolvency history, bankruptcy status, financial fitness to serve as director, or due diligence screening. Uses person slug. Parameters: - slug (string, required): Person slug from shared.people (e.g. "john-smith") --- #### get_company_directorships GET /api/v1/directorships/{slug} Get full directorship history for any person from the NZ Companies Register. Shows all company roles (NZX-listed + private companies), current and historical, with company status (active/struck off/liquidating) and failure rate analysis. Use when asked about a person's full board network, private company roles, directorship workload, or company failure history. Uses person slug. Parameters: - slug (string, required): Person slug from shared.people (e.g. "rob-campbell") --- #### get_director_workload GET /api/v1/director-workload/{slug} Get workload analysis for a director — current NZX board seats, active Companies Office directorships, overboarding status, board meeting attendance rate, tenure at each board, and chair/committee roles. Uses person slug. Parameters: - slug (string, required): Person slug from shared.people (e.g. "rob-campbell") --- #### get_company_failures GET /api/v1/company-failures/{slug} Get a director's association with failed or distressed companies — struck off, liquidated, in receivership. Shows failure rate, timeline of failures, and whether the person was director before/during/after failure. Uses person slug. Parameters: - slug (string, required): Person slug from shared.people (e.g. "rob-campbell") --- #### get_capital_raise_sentiment GET /api/v1/capital-raise-sentiment/{ticker} — query: year, type, context Analyze whether capital raises by an NZX company were done from a position of financial strength or desperation. Returns sentiment, financial health, insider activity around ±30 days, and post-raise stock performance (30/90/180 day returns) for each raise. Composite score classifies as "strength", "neutral", or "desperation". Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "FPH") - year (string, optional): Filter by year or range (e.g. "2024" or "2020-2024") - type (string, optional): Filter by raise type (comma-separated): placement, rights_issue, spp, ipo, bond, options_exercise - context (string, optional): Filter by context classification: "strength", "neutral", or "desperation" --- #### get_announcement_alerts GET /api/v1/announcement-alerts List the authenticated user's announcement alert subscriptions. Returns active alert configurations for NZX announcement content matching by keyword, announcement type, ticker, and sector. --- #### get_board_effectiveness GET /api/v1/board-effectiveness/{ticker} Get comprehensive board effectiveness dashboard for a company — 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, and remuneration context. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_insider_ownership GET /api/v1/insider-ownership/{ticker} Get insider/director ownership data for an NZX company. Returns total director shareholdings, directors with shares vs board size, net buying/selling (12m), individual director holdings with share counts, and recent insider trades. Use when asked about insider ownership, skin in the game, director holdings, founder holdings, or insider trading activity for a specific company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_factor_validation GET /api/v1/factor-validation — query: significance, category Get NZX factor validation results — 16 backtested financial factors (7 statistically significant, 9 moderate) plus 7 proprietary signal backtests. Returns Information Coefficients (IC), t-statistics, hit rates, direction (LONG/SHORT), and significance levels. Also includes proprietary signals: director resignation clusters, management credibility, earnings tone, insider clusters, auditor rotation, F-score/Z-score, dividend cut prediction. Use when asked about which factors work on the NZX, alpha signals, backtested strategies, or factor investing. Parameters: - significance (string, optional): Filter by significance level: strong, moderate, or both (comma-separated) - category (string, optional): Filter by category: Valuation, Growth, Profitability, Leverage, Cash Flow, Dividends (comma-separated) --- #### get_factor_model GET /api/v1/factor-model — query: sector, factor, grade, limit Get NZ Equity Factor Model — market-wide 6-factor scores (Value, Growth, Quality, Momentum, Dividends, Governance) for all NZX companies. Sector-relative percentile ranking (0-100) with A-F grades. Filter by sector, factor, grade. Use for factor-based stock selection and quantitative screening. Parameters: - sector (string, optional): Filter by sector (e.g. "Healthcare") - 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) --- #### get_board_benchmark GET /api/v1/board-benchmark/{ticker} Get quantitative board benchmarking for a company vs sector and market-cap peers — 6 dimensions: board size, independence ratio, gender diversity, skills coverage, meeting frequency, fee levels. Returns percentile rankings, P25/P75 ranges, 3-year trend, and overall assessment with strengths/improvements. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_chair_ceo_alignment GET /api/v1/chair-ceo-alignment/{ticker} Get Chair vs CEO communication alignment analysis for a company. Compares Language Intelligence Scores (LIS), sentiment, conviction, and transparency between Chair and CEO AGM speeches. Flags divergence (>10 point LIS gap) as a governance signal. Shows historical trend (widening/narrowing). Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_succession_plan GET /api/v1/succession-plan/{ticker} Get succession risk assessment for a company board — 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, and ranked successor candidates. IOD-8 feature for board search firms and governance consultants. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_director_demographics GET /api/v1/director-demographics/{ticker} Get board demographics for a company — estimated director ages, international experience (countries worked in), professional body memberships, career length, and gender split. Uses AI-extracted data from director biographies. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") --- #### get_government_contracts GET /api/v1/government-contracts/{ticker} — query: limit, from Get government contracts awarded to an NZX-listed company via GETS (Government Electronic Tenders Service). Shows contract history, agencies, values, and government revenue exposure. Useful for assessing government dependency, procurement relationships, and public sector revenue concentration. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "SPK", "AIR", "FPH") - limit (number, optional): Max contracts to return (default 100, max 500) - from (string, optional): Filter contracts awarded on or after this date (YYYY-MM-DD) --- #### get_hidden_connections GET /api/v1/hidden-connections/{ticker} Get hidden connections for an NZX company — directors who share private company board seats with directors of other NZX issuers. These relationships are not visible from NZX filings alone, sourced from the NZ Companies Register. Returns connection pairs, shared companies, connection density, and most-connected director. Useful for identifying undisclosed relationships, potential conflicts of interest, and board network analysis. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR", "SPK", "FPH") --- #### get_director_questionnaire GET /api/v1/director-questionnaire/{ticker}/{director_slug} Get a pre-filled D&O (Directors & Officers) insurance questionnaire for a specific director at a specific company. Auto-fills 75-85% of a typical questionnaire from cross-platform data: all directorships (NZX + private + charity + iwi + public sector), insider trades, shareholdings, skills matrix, qualifications, committees, regulatory actions, court cases, disciplinary records, political connections, career history, board fees, and executive compensation. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR") - director_slug (string, required): Director slug from their profile URL (e.g. "rob-campbell", "scott-st-john") --- #### check_thesis GET /api/v1/thesis/{ticker} — query: direction Check if an investment thesis for an NZX company is still valid. Compares thesis direction (bullish/bearish/neutral) against 4 independent signals: analyst consensus, fair value model, management credibility, and insider activity. Returns invalidation score (0-100) and signal breakdown. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "MEL") - direction (string, required): Your thesis direction Options: bullish | bearish | neutral. --- #### get_liquidity_score GET /api/v1/liquidity/{ticker} Get Kyle's Lambda liquidity score for an NZX company. Measures price impact per unit of volume using Kyle (1985) regression model. Higher lambda = more illiquid / more informed trading. Includes liquidity rating (A-E), average daily volume, average daily traded value, and volume trend. Use when user asks about liquidity, trading volume, price impact, market depth, or how tradeable a stock is. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_deep_research_qa GET /api/v1/deep-research-qa/{ticker} Validate a deep research report against ground-truth NZXplorer data. Cross-checks financial figures (revenue, NPAT), governance scores (GRS), accounting quality (M/F/Z-scores), director counts, ESG data, and investment thesis structure. Returns per-check pass/fail/warn status, overall confidence score (0-100), and critical failures. Use after generating a deep research report to verify accuracy before sharing. Parameters: - ticker (string, required): NZX ticker symbol --- #### get_climate_gap_analysis GET /api/v1/climate-gap-analysis/{ticker} Get NZ Climate Standards (NZ CS 1-4) gap analysis for an NZX company. Assesses 23 XRB requirements across governance (5), strategy (6), risk management (4), and metrics & targets (8). Returns per-requirement status (met/partial/gap), evidence, recommendations, overall score (0-100), and mandatory reporter status. Use when the user asks about climate compliance, NZ CS readiness, XRB requirements, or TCFD gaps. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "MEL", "CEN", "AIR") --- #### get_esg_disclosure_gap GET /api/v1/esg-disclosure-gap/{ticker} — query: framework Get multi-framework ESG disclosure gap analysis for an NZX company. Compares against three international standards: TCFD (11 recommendations), ISSB/IFRS S2 (climate disclosure requirements), and NZ XRB Climate Standards (NZ CS 1-4). Returns per-framework scores, requirement-level gaps with evidence and recommendations, mandatory reporter status, and overall multi-framework readiness score. Use when the user asks about ESG gaps, disclosure readiness, TCFD compliance, ISSB alignment, or multi-framework comparison. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "MEL", "CEN", "AIR") - framework (string, optional): Filter to a specific framework (default: all) Options: tcfd | issb | nzcs | all. --- #### get_volume_anomalies GET /api/v1/volume-anomalies — query: ticker, days, min_zscore Get volume anomaly detection for NZX stocks. Uses z-score analysis on daily OHLCV data to identify three types of unusual volume: spikes (single day z-score > threshold), clusters (3+ days of >2x avg volume in 7-day window), and price-volume divergences (big volume + small price move). Cross-references announcements within 5 trading days. Especially valuable on the thin NZX market where even modest institutional flows create detectable anomalies. Use when the user asks about unusual volume, trading activity, accumulation, distribution, or pre-announcement patterns. Parameters: - ticker (string, optional): Optional NZX ticker symbol to filter (e.g. "FPH"). 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) --- #### get_my_portfolio GET /api/v1/portfolio/enriched Get the authenticated user's portfolio holdings with enriched data including current prices, unrealized P&L, GRS governance scores, dividend yields, risk flags, upcoming events (dividends, meetings), recent insider trades, and sector exposure breakdown. Use this tool whenever the user asks about "my portfolio", "my holdings", "my stocks", "my exposure", "how am I doing", "what should I worry about", or any question that relates to their personal investment portfolio. Returns null if the user has no portfolio. --- #### get_remuneration_compliance GET /api/v1/remuneration-compliance/{ticker} Get the Remuneration Disclosure Compliance Scorecard for an NZX company. Scores against 8 NZX Corporate Governance Code v1.7 criteria: individual fee disclosure, CEO compensation breakdown, STI/LTI hurdle disclosure, remuneration policy, committee independence, peer benchmarking, AGM say-on-pay vote, and termination payment disclosure. Returns 0-100 score with A-F grade. Use when asked about remuneration compliance, disclosure quality, pay transparency, or governance code alignment. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### get_disclosure_language GET /api/v1/disclosure-language/{ticker} Analyze disclosure language evolution for an NZX company. Detects shifts in hedging patterns, sentiment volatility, buried risk frequency, guidance consistency, and forward-looking statement density. Returns 5 dimension scores (0-100) and an overall rating (Transparent/Adequate/Opaque/Concerning). Use when asked about disclosure quality, language analysis, hedging, transparency trends, or communication style. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### get_interest_register GET /api/v1/interest-register/{ticker} Get the automated Companies Act s189 interest register for an NZX company. Compiles each director's interests: other NZX board seats, charity trustee roles, public sector appointments, substantial shareholdings, recent insider trades, and professional directorships. Cross-references data from all four NZXplorer platforms. Use when asked about director interests, conflicts of interest, related party positions, or board independence. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### get_agm_notice_draft GET /api/v1/agm-notice/{ticker} Generate an automated draft Notice of Annual Meeting for an NZX company. Identifies directors due for re-election (3-year rotation), auditor re-appointment, fee pool resolution, and capital raise ratifications. Produces ~80% complete draft for company secretary review. Use when asked about AGM preparation, meeting notices, director re-election, or proxy forms. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### get_greenwashing_detection GET /api/v1/greenwashing/{ticker} Analyze ESG greenwashing risk for an NZX company. Compares sustainability claims in announcements against actual ESG metrics (emissions, diversity, safety). Returns narrative score, evidence score, alignment score, and gap rating. A high gap score suggests potential inconsistency between reported narrative and measured outcomes. Use when asked about ESG claims, sustainability narrative, greenwashing, or environmental reporting consistency. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### get_disclosure_score GET /api/v1/nzx-disclosure-score/{ticker} Get the NZX Disclosure Transparency Score for an NZX company. Scores 0-100 across 5 dimensions: announcement frequency, disclosure completeness, guidance quality, timeliness, and sentiment transparency. Returns overall score, rating (Exemplary/Strong/Adequate/Limited/Minimal), and per-dimension breakdowns. Use when asked about disclosure quality, transparency score, reporting transparency, or how well a company communicates with the market. Parameters: - ticker (string, required): NZX ticker symbol (e.g. FPH) --- #### subscribe_insider_alerts POST /api/v1/alerts/insider-trades Create an insider trading alert subscription. Monitors insider trades (director share transactions) for specified tickers and delivers notifications via email, webhook, Slack, or Teams. Supports filtering by minimum trade value and trade types (Buy, Sell, Exercise, Transfer). Use when asked to set up insider trade alerts, watch for director buying/selling, or monitor insider activity. Parameters: - name (string, optional): Friendly name for this alert subscription (default: "Insider Trade Alerts") - tickers (array, optional): NZX ticker symbols to watch (e.g. ["AIR", "FPH"]). Empty array = all companies. - min_value (number, optional): Minimum trade value in NZD to trigger alert (e.g. 10000) - trade_types (array, optional): Trade types to watch: Buy, Sell, Exercise, Transfer, Other - delivery_method (string, optional): Delivery method: email, webhook, slack, or teams (default: email) - email_address (string, required): Email address for delivery (required if delivery_method is email) --- #### subscribe_people_alerts POST /api/v1/alerts/people Create a person alert subscription to monitor a specific individual for events such as board appointments, resignations, insider trades, compensation changes, regulatory actions, or role changes. Use when a user wants to track or follow a person, set up alerts for a director or executive, or be notified about changes involving a specific individual. Parameters: - person_id (number, optional): The person_id from shared.people (if known) - person_name (string, required): Full name of the person to monitor (e.g. "Scott St John") - event_types (array, required): Event types to monitor: appointment, resignation, insider_trade, compensation_change, regulatory_action, role_change - min_transaction_value (number, optional): Minimum transaction value filter for insider trades (e.g. 5000) - delivery_method (string, optional): Delivery method: email, webhook, slack, or teams (default: email) - email_address (string, optional): Email address for delivery (required if delivery_method is email) --- #### get_chair_network GET /api/v1/chair-network Analyze the NZX board chair interlock network. Shows which chairs sit on multiple boards and how they are interconnected. Returns a list of all current chairs with their board seats, interlock pairs (chairs who share a board), and network metrics including total chairs, serial chairs (2+ boards), most connected chair, and average boards per chair. Use when asked about chair networks, board interlocks among chairs, serial chairs, or how NZX board chairs are connected. --- #### get_knowledge_graph GET /api/v1/knowledge-graph Get the full NZX-wide director/company interlock knowledge graph. Returns all nodes (directors + issuers), edges (board seats + shared-director links), Louvain community clusters, power broker rankings (degree × betweenness centrality), and network statistics (density, avg/max degree, community count). Use when asked about board interlocks, director networks, power brokers, most connected directors, governance communities, or NZX network analysis. --- #### get_knowledge_graph_shortest_path GET /api/v1/knowledge-graph/shortest-path — query: from, to Find the shortest connection path between any two NZX directors via shared board seats. Uses bidirectional BFS through the director/company interlock graph. Returns the full path (directors and companies traversed) and the degrees of separation. Use when asked how two directors are connected, degrees of separation, or the link between two people in the NZX network. Parameters: - from (string, required): Slug of the source director (e.g. "joan-withers") - to (string, required): Slug of the target director (e.g. "mark-cairns") --- #### get_financial_distress GET /api/v1/financial-distress/{ticker} Get financial distress early warning for a company. 8-factor model combining Altman Z-Score, Piotroski F-Score, Beneish M-Score, interest coverage, current ratio, revenue trend, cash flow health, and governance risk into a distress probability (0-100%). Risk levels: Healthy / Watch / Elevated / High / Critical. Based on patterns from historical NZ corporate failures (CBL, Wynyard, Pumpkin Patch). Use when asked about financial health, distress risk, bankruptcy probability, or going concern risk. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH") --- #### check_governance_policy GET /api/v1/governance-policy-check — query: preset, tickers Run a governance policy compliance check across all NZX companies (or a subset). Evaluates board independence, gender diversity, director tenure, board size, non-exec chair, attendance, GRS score, auditor independence, committee structure, and financial health against configurable thresholds. 8 presets available (nzxplorer, conservative, progressive, market-friendly, iss-nz, nz-super, russell-nz, vanguard-aunz). Returns per-company pass/fail with rule breakdown and aggregate compliance statistics. Use when asked about governance compliance, policy screening, institutional governance standards, or market-wide governance scanning. Parameters: - preset (string, optional): Policy preset ID (default: "nzxplorer"). Options: nzxplorer, conservative, progressive, market-friendly, iss-nz, nz-super, russell-nz, vanguard-aunz - tickers (string, optional): Comma-separated ticker list to check (default: all NZX companies) --- #### get_team_members GET /api/account/team/members Get the list of team members for the authenticated user's team, including roles (admin/analyst/viewer), invite status, and join dates. Corporate tier only. --- #### get_esg_target_credibility GET /api/v1/esg-target-credibility/{ticker} Assess the credibility of an NZX company's net zero and emissions reduction targets. Evaluates Scope 3 disclosure (materiality, trend, coverage), target credibility (7 factors: emissions trajectory, SBTi validation, timeline, baseline, multi-year data, intensity metrics, Scope 3 inclusion). Returns combined score (0-100), credibility rating (Strong/Moderate/Weak/No Target), sector materiality assessment, and key findings. Use when asked about climate targets, net zero credibility, Scope 3 emissions, or ESG target quality. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_disclosure_language_benchmark GET /api/v1/disclosure-language-benchmark/{ticker} Get sector-benchmarked disclosure language analysis for an NZX company. Returns the company's absolute disclosure language score plus sector-adjusted score (relative to sector peers), sector percentile, and sector average breakdown by dimension. Mining companies naturally hedge more — this tool adjusts for that. Use when asked about how a company's disclosure language compares to its sector peers, or whether hedging/opacity is normal for its industry. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_activist_vulnerability GET /api/v1/activist-vulnerability/{ticker} Get activist vulnerability score for an NZX company. 8-factor composite (0-100) assessing vulnerability to activist campaigns: governance risk, ownership concentration, director failure rates, pay-performance misalignment, board entrenchment, shareholder dissent, capital allocation efficiency, political connections. Rating: Very High/High/Elevated/Moderate/Low. Use when asked about activist risk, governance vulnerability, board accountability, or whether a company could be an activist target. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_esg_disclosure_benchmark GET /api/v1/esg-disclosure-benchmark/{ticker} Get ESG disclosure quality benchmark for an NZX company. 3-component composite (0-100): claim-evidence alignment (40%, narrative vs actual ESG data), disclosure transparency (30%, hedging/sentiment/buried risks), ESG data coverage (30%, emissions/diversity/safety breadth). Sector benchmarked with percentile. Rating: Exemplary/Strong/Adequate/Weak/Poor. Use when asked about ESG reporting quality, greenwashing risk, disclosure benchmarking, or how a company's ESG reporting compares to peers. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_annual_report_quality GET /api/v1/annual-report-quality/{ticker} Get annual report quality score for an NZX company. 8-dimension composite (0-100): financial disclosure depth, segment reporting, governance disclosure, ESG reporting, director bio quality, board meeting transparency, earnings presentation quality, stakeholder communication frequency. Sector benchmarked with percentile. Rating: Exemplary/Strong/Good/Adequate/Weak. Use when asked about annual report quality, disclosure completeness, reporting standards, or how transparent a company's reporting is. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_governance_responses GET /api/v1/governance-responses/{ticker} Get approved governance flag responses submitted by a company's IR team. Shows company context for governance flags (GRS components, remuneration compliance, proxy advisory, board effectiveness, activist vulnerability). Use when asked about a company's response to governance concerns, or when presenting governance flags to give the company's perspective. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") --- #### get_daily_market_wrap GET /api/v1/market-wrap — query: days Get the daily NZX market wrap — a market-wide digest covering all active NZX issuers. Returns price moves, market breadth (gainers/decliners/unchanged), announcements, insider trades, upcoming dividends, board changes, plus AI-generated video script and written narrative summary. Use when asked about overall market conditions, today's market, what happened on the NZX, or market summary. Parameters: - days (number, optional): Lookback days (1-7, default 7). Use 1 for last trading day, 7 for the week. --- #### get_market_changes GET /api/v1/market-changes — query: hours, limit, tickers Get a market-wide activity feed showing significant events from the last 48 hours — board changes, insider trades, dividend announcements, earnings, takeovers, and significant price moves. Events are severity-ranked (critical/high/medium/low). Use when asked what happened on the market, recent changes, market activity, or what's new across NZX. Parameters: - hours (number, optional): Lookback period in hours (default 48, max 168) - limit (number, optional): Max items to return (default 30, max 100) - tickers (string, optional): Comma-separated ticker filter for watchlist mode (e.g. "AIR,SPK,FPH") --- #### get_ir_briefing GET /api/v1/ir-briefing/{ticker} Get a per-company IR briefing with change detection. Returns current data snapshot, prior period snapshot, and change flags showing what has changed (governance score, board size, chair, CEO, sentiment, independence, ownership concentration, insider direction, auditor). Use when asked what changed for a company, company intelligence briefing, or IR briefing. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR") --- #### get_digital_presence GET /api/v1/digital-presence/{ticker} Get digital presence metrics, AI visibility, and perception gap analysis for an NZX company. Shows how investors find the company online, what AI search engines say about it, and where market perception diverges from filing truth. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR") --- #### get_officer_history GET /api/v1/officers/{ticker}/history — query: type, status, role, from, to Get the full historical officer timeline for an NZX company — every director and executive who has ever held a role, with start/end dates, tenure, status, and committees. Includes both board members (from director_appointments) and C-suite executives (from management_team). Each officer includes a stable permanent_id (NZX-P-NNNNNN) for cross-referencing. Supports FDC3 contactList format. Use when asked about past leadership, board turnover, executive changes, or who used to run a company. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH", "AIR", "SPK") - type (string, optional): Filter by officer type: board, executive, or all (default: all) - status (string, optional): Filter by status: current, resigned, retired (comma-separated) - role (string, optional): Filter by role keyword: chair, ceo, cfo, director (comma-separated) - from (string, optional): Start date filter (YYYY-MM-DD) — appointments after this date - to (string, optional): End date filter (YYYY-MM-DD) — appointments before this date --- #### get_compensation_benchmark GET /api/v1/compensation-benchmark/{role} — query: year, sector, market_cap Get compensation percentile benchmarking for a specific executive or board role across all NZX companies. Returns P10/P25/P50/P75/P90 percentiles, mean, min, max, plus breakdowns by sector and market cap tier (micro/small/mid/large). Valid roles: ceo, cfo, coo, chair, director, cto, cio, cro, general-counsel, company-secretary. Use when asked about pay benchmarks, market rates, how much CEOs/CFOs earn, or whether a company overpays vs peers. Parameters: - role (string, required): Role to benchmark: ceo, cfo, coo, chair, director, cto, cio, cro, general-counsel, company-secretary - year (number, optional): Financial year to filter (default: latest available per company) - sector (string, optional): Filter by sector (e.g. "Healthcare", "Energy") - market_cap (string, optional): Filter by market cap tier: micro, small, mid, large --- #### get_section_evolution GET /api/v1/section-evolution/{ticker} — query: type, compare Get how a specific section of annual reports (risk factors, governance, remuneration, accounting policies, strategy, outlook) has evolved across years for a company. Returns YoY diffs with added/removed lines and word count trends. Use when asked about risk disclosure changes, governance statement evolution, remuneration policy changes, or how reporting has changed over time. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "FPH") - type (string, required): Section type: risk, governance, remuneration, accounting_policy, strategy, outlook, chairman, ceo, esg, audit_opinion - compare (string, optional): "all" for all years or "latest" for last 2 years only (default: "all") --- #### get_transcript_diffs GET /api/v1/transcript-diffs/{ticker} Compare earnings presentation transcripts across periods for a company. Returns language diffs, tone shifts (optimistic/cautious/defensive), and sentiment changes between consecutive presentations. Use when asked about management language changes, tone shifts, how earnings presentations have changed, or credibility tracking. Parameters: - ticker (string, required): NZX ticker symbol (e.g. "AIR") ---