{ "openapi": "3.1.0", "info": { "title": "NZXplorer API", "version": "1.157.0", "description": "Comprehensive NZX market data, governance intelligence, and proxy advisory API covering 130 issuers on the New Zealand Exchange. Provides structured access to company fundamentals, director intelligence, insider trades, financial statements, ESG data, dividend analytics, proxy advisory reports, and more.\n\nAll monetary values in financial statement endpoints (income_statements, balance_sheets, cash_flow_statements, earnings_results) are in NZD thousands unless otherwise noted. Dividends per share (dps_cents) are in cents. Ratios are unit-free percentages.", "contact": { "name": "NZXplorer API Support", "email": "hello@nzxplorer.co.nz", "url": "https://nzxplorer.co.nz/developers" }, "license": { "name": "Proprietary", "url": "https://nzxplorer.co.nz/terms" }, "x-logo": { "url": "https://nzxplorer.co.nz/logo.png" } }, "servers": [ { "url": "https://nzxplorer.co.nz/api/v1", "description": "Production" } ], "security": [ { "ApiKeyHeader": [] }, { "ApiKeyQuery": [] } ], "tags": [ { "name": "Alerts", "description": "Webhook, email, and Zapier alert subscriptions" }, { "name": "Analytics", "description": "Backtesting, investment checks, and alpha scores" }, { "name": "Charities", "description": "Registered NZ charities, officers, and briefings" }, { "name": "Companies", "description": "NZX-listed company data (131 issuers)" }, { "name": "Copilot", "description": "Natural language query interface and MCP integration" }, { "name": "Corporate Actions", "description": "Takeovers, capital raises, credit ratings, deal advisers" }, { "name": "Directors", "description": "Director profiles, board composition, skills, and due diligence" }, { "name": "Dividends", "description": "Dividend history, safety scores, and analytics" }, { "name": "ESG", "description": "Environmental, social, and governance data with climate standards" }, { "name": "Earnings", "description": "Structured earnings results, themes, guidance, and presentations" }, { "name": "Export", "description": "Bulk data downloads and XLSX export" }, { "name": "Financials", "description": "Financial statements, metrics, ratios, and xBRL" }, { "name": "Governance", "description": "Governance Risk Scores, compliance, political connections, KYC screening" }, { "name": "Insider Trades", "description": "Director share transactions, substantial shareholders, and beneficial ownership" }, { "name": "Macro", "description": "NZ macroeconomic data, OCR history, and company exposure" }, { "name": "Market Data", "description": "Stock prices, performance, technical signals, and factor models" }, { "name": "Market Intelligence", "description": "Signals, anomalies, sentiment, semantic search, and risk language" }, { "name": "Property", "description": "REIT property portfolios, climate risk, and tenant data" }, { "name": "Proxy Advisory", "description": "Proxy reports, AGM resolutions, and voting recommendations" }, { "name": "Public Sector", "description": "Councillor interests, select committees, and supplier governance" }, { "name": "Research", "description": "Deep research, briefings, company one-pagers, and network analysis" }, { "name": "Screener", "description": "Multi-column stock screener with smart presets" }, { "name": "Stewardship", "description": "Stewardship reports, voting policies, and fund manager votes" }, { "name": "System", "description": "Health checks and system status" }, { "name": "Widgets", "description": "Embeddable widgets and portfolio management" } ], "paths": { "/companies": { "get": { "operationId": "listCompanies", "summary": "List Companies", "description": "Browse all 131 NZX-listed companies with sector filtering and search.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search by company name or ticker", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by: ticker, name, sector, market_cap (default: ticker)", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Sort order: asc or desc (default: asc)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 500 (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/companies/{ticker}": { "get": { "operationId": "getCompany", "summary": "Company Detail", "description": "Get detailed company profile with optional directors, financials, governance score, and latest price.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated: directors, financials, governance, price, all", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/directors": { "get": { "operationId": "listDirectors", "summary": "List Directors", "description": "Browse all 2,000+ NZX company directors with search and company filtering.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search by director name", "schema": { "type": "string" } }, { "name": "current", "in": "query", "required": false, "description": "If true with company filter, only current directors", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 500 (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Directors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/directors/{slug}": { "get": { "operationId": "getDirector", "summary": "Director Detail", "description": "Get full director profile with board appointments, optional share trades and board fee history. Note: remuneration returns board fees, not executive compensation (coming in Phase 2).", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated: trades, remuneration, all", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Director Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/management-team/{ticker}": { "get": { "operationId": "getManagementTeam", "summary": "Management Team", "description": "Get the management team (C-suite executives) for an NZX company. Returns current or historical executives with normalized roles, tenure, and linked person profiles.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "Filter by normalized role: CEO, CFO, COO, CTO, CIO, CHRO, CLO, CMO, CSO, COO, COMPANY_SECRETARY, GM, MD, OTHER", "schema": { "type": "string" } }, { "name": "current", "in": "query", "required": false, "description": "If true (default), only current executives. Set to false for full history.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Management Team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/prices/{ticker}": { "get": { "operationId": "getPrice", "summary": "Stock Prices", "description": "Historical OHLCV daily stock prices plus intraday snapshots (15-minute delay). The response includes a `latest` object with the most recent intraday price, change%, day high/low, and volume when available.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Last N days of prices", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max records, up to 2000 (default: 365)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock Prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/governance": { "get": { "operationId": "listGovernance", "summary": "Governance Scores", "description": "GRS v2.0 scores for all 131 NZX companies. 0-100 scale across 6 governance components.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "sector", "in": "query", "required": false, "description": "Filter by sector", "schema": { "type": "string" } }, { "name": "rating", "in": "query", "required": false, "description": "Filter by rating tier: Excellent, Very Good, Good, Adequate, Poor, Very Poor", "schema": { "type": "string" } }, { "name": "min_score", "in": "query", "required": false, "description": "Minimum total score", "schema": { "type": "number" } }, { "name": "max_score", "in": "query", "required": false, "description": "Maximum total score", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by: total_score or any component score", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Governance Scores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/announcements": { "get": { "operationId": "listAnnouncements", "summary": "Announcements", "description": "Search 64,000+ NZX market announcements (2017-2026) with deep full-text search across titles AND 62,500+ extracted PDF documents. Find any mention of a topic, company, or event across 10 years of NZX filings. Supports cursor-based pagination via ?after= and ?before= params — responses include meta.next_cursor, meta.prev_cursor, and meta.has_more when using cursor mode. Server uses parseCursorPagination() + buildCursorMeta() helpers.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Full-text search across announcement titles AND PDF document content (62,500+ PDFs extracted)", "schema": { "type": "string" } }, { "name": "ticker", "in": "query", "required": false, "description": "Filter by company ticker", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Announcement type: SHINTR, GENERAL, MKTUPDTE, MEETING, SECISSUE, FLLYR, HALFYR, DVDEND", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor for next page (from meta.next_cursor). Switches to cursor-based pagination mode.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor for previous page (from meta.prev_cursor). Switches to cursor-based pagination mode.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Announcements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/insider-trades": { "get": { "operationId": "listInsiderTrades", "summary": "Insider Trades", "description": "Director share transactions — 9,400+ buy/sell/exercise records across 10 years (2017-2026). See who is buying and selling NZX stocks. Supports cursor-based pagination via ?after= and ?before= params — responses include meta.next_cursor, meta.prev_cursor, and meta.has_more when using cursor mode.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 500 (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor for next page (from meta.next_cursor). Switches to cursor-based pagination mode.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor for previous page (from meta.prev_cursor). Switches to cursor-based pagination mode.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Insider Trades", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/financials/{ticker}": { "get": { "operationId": "getFinancial", "summary": "Financial Statements", "description": "Income statements, balance sheets, cash flows, and financial ratios. 367 company-years, FY2010-2025.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "statement", "in": "query", "required": false, "description": "Filter: income, balance, cashflow, ratios (comma-separated)", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter by period type: annual or interim (default: both)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Financial Statements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/income-statement/{ticker}": { "get": { "operationId": "getIncomeStatement", "summary": "Income Statement", "description": "Dedicated income statement endpoint. Revenue, COGS, gross profit, EBITDA, EBIT, net profit, EPS, DPS. All monetary values in NZD thousands.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter: annual or interim", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Income Statement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/balance-sheet/{ticker}": { "get": { "operationId": "getBalanceSheet", "summary": "Balance Sheet", "description": "Dedicated balance sheet endpoint. Assets, liabilities, equity, cash, debt, receivables, inventories, PPE, goodwill. All monetary values in NZD thousands.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter: annual or interim", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance Sheet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/cash-flow/{ticker}": { "get": { "operationId": "getCashFlow", "summary": "Cash Flow Statement", "description": "Dedicated cash flow endpoint. Operating, investing, financing cash flows, free cash flow, capex. All monetary values in NZD thousands.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter: annual or interim", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cash Flow Statement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/financials/{ticker}/xbrl": { "get": { "operationId": "getFinancialXbrl", "summary": "iXBRL Financial Statements", "description": "Machine-readable Inline XBRL (iXBRL) financial documents. 54 IFRS taxonomy concepts across income statements, balance sheets, cash flows, and ratios. 116 companies, FY2010-2025.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year (default: latest)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Output format: html (iXBRL document), json (structured facts), llm (token-optimized)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "iXBRL Financial Statements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/earnings/{ticker}": { "get": { "operationId": "getEarning", "summary": "Earnings Results", "description": "Structured earnings from FLLYR/HALFYR announcements. 1,079 rows, 120 issuers, 2019-2026 (8 years).", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year or range", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter: annual or interim", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Earnings Results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ir-dashboard/{ticker}": { "get": { "operationId": "getIrDashboard", "summary": "IR Dashboard", "description": "Comprehensive Investor Relations dashboard for NZX-listed companies. Aggregates IR Quality Score, announcement sentiment, shareholder composition, insider activity, governance, earnings trajectory, disclosure frequency, and peer comparison into a single response.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "IR Dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/compliance-calendar/{ticker}": { "get": { "operationId": "getComplianceCalendar", "summary": "Compliance Calendar", "description": "Rolling NZX regulatory deadline tracker for a specific company. Computes 5 deadline types from balance date: preliminary announcement (60 days), annual report (3 months), half-year report, AGM (5 months), and AGM notice. Cross-references actual NZX filings to show filed status.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compliance Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/alerts/board-events": { "post": { "operationId": "createAlertsBoardEvents", "summary": "Board Event Webhooks", "description": "Trigger dispatch of board-relevant event alerts to active webhook subscriptions. Detects 6 event types: director appointments/departures, insider trade clusters, GRS score drops, dividend cuts, and AGM resolution failures. Cron-triggered.", "tags": [ "Directors" ], "x-tier": "free", "responses": { "200": { "description": "Board Event Webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/signals/detect": { "post": { "operationId": "runSignalsDetect", "summary": "Signal Fusion Detection", "description": "Detect composite multi-signal anomalies across all NZX issuers. Identifies 12 patterns: insider selling + earnings miss, director exodus, governance deterioration, dividend at risk, auditor red flag, CEO+CFO double departure, capital raise dilution, insider buying spree, earnings tone shift, multi-signal stress, sentiment divergence, and sentiment cluster. Returns detected composite signals sorted by severity. Composite signals are also included in webhook alert dispatch (signal type: composite_signal).", "tags": [ "Market Intelligence" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lookback": { "type": "number", "description": "Days to look back for signal detection (default: 90)" } } } } } }, "responses": { "200": { "description": "Signal Fusion Detection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/narrative-tracker/{ticker}": { "get": { "operationId": "getNarrativeTracker", "summary": "Narrative Tracker", "description": "YoY management messaging evolution. Combines earnings themes, sentiment, guidance direction, and AGM speech intelligence into a unified timeline with tone shifts and topic churn.", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Narrative Tracker", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/earnings-themes/{ticker}": { "get": { "operationId": "getEarningsTheme", "summary": "Earnings Themes", "description": "AI-extracted themes from earnings announcements. Key topics, management tone (optimistic/cautious/defensive/mixed/neutral), forward-looking statement count. 990 results themed across 120 issuers.", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year or range (e.g., 2023 or 2020-2023)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Earnings Themes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/guidance-changes/{ticker}": { "get": { "operationId": "getGuidanceChange", "summary": "Guidance Changes", "description": "Management guidance history for an NZX issuer — upgrades, downgrades, maintains, accuracy scores, tone shifts. 938 structured guidance records with 176 accuracy scores across 120+ issuers.", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Filter by fiscal year (e.g., 2025)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max records to return (default 100, max 500)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guidance Changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ir-quality/{ticker}": { "get": { "operationId": "getIrQuality", "summary": "IR Quality Score", "description": "Disclosure quality scoring across 5 dimensions: timeliness, completeness, readability, frequency, governance transparency. Grounded in OECD, CFA, S&P, and NIRI frameworks. 131 issuers scored with per-issuer trajectories.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "IR Quality Score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/peer-mentions/{ticker}": { "get": { "operationId": "getPeerMention", "summary": "Peer Mentions", "description": "Cross-company business relationships extracted from 62,000+ NZX announcements. 12,297 peer mentions classified into 10 relation types (supplier, customer, partner, competitor, joint_venture, acquirer, subsidiary, licensee, advisor, shareholder) via Claude Haiku. Shows which companies mention this ticker, relationship types, context snippets, and network summary with relation breakdown.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Peer Mentions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/broker-coverage/{ticker}": { "get": { "operationId": "getBrokerCoverage", "summary": "Broker Coverage", "description": "Analyst coverage, consensus ratings, and price targets for an NZX company. Includes which brokers and analysts cover the stock, historical ratings, forecasts, and research notes.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated sections: ratings, forecasts, reports, summary, all (default: ratings,summary)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Broker Coverage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/estimates/{ticker}": { "get": { "operationId": "getEstimate", "summary": "Consensus Estimates", "description": "Unified analyst consensus estimates combining Yahoo Finance consensus, company guidance, broker ratings/forecasts, earnings surprise probability, and valuation context. First NZ platform with unified consensus view.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Consensus Estimates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/announcements/{id}/extract": { "post": { "operationId": "extractAnnouncementsExtract", "summary": "Announcement PDF Reader", "description": "On-demand AI extraction from announcement PDFs. Returns summary, key figures, sentiment, entities, topics, and risk flags. Results are cached. Pro+ tier required.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Announcement ID from /api/v1/announcements results", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Announcement PDF Reader", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deal-advisers/{ticker}": { "get": { "operationId": "getDealAdviser", "summary": "Deal Advisers", "description": "Professional advisers (law firms, investment banks, valuers) who advised on capital raises and takeovers for an NZX company. Shows adviser roles, deal values, and firm details. Part of Capital Markets Graph (#671).", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "deal_type", "in": "query", "required": false, "description": "Filter: capital_raise or takeover", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "Filter by adviser role: legal_issuer, underwriter, lead_manager, etc.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal Advisers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deal-insider-signals/{ticker}": { "get": { "operationId": "getDealInsiderSignal", "summary": "Deal Insider Signals", "description": "Detect insider trading patterns before capital raises and takeovers. Cross-references director share transactions with deal announcements to flag pre-deal buying or selling within a configurable window. Use ticker ", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback window: 30, 60, or 90 days (default 90)", "schema": { "type": "number" } }, { "name": "deal_type", "in": "query", "required": false, "description": "Filter: capital_raise or takeover", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal Insider Signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deal-prediction/{ticker}": { "get": { "operationId": "getDealPrediction", "summary": "Deal Flow Prediction", "description": "8-factor capital raise probability scoring (0-100) for NZX issuers. Factors: raise frequency, time since last raise, cash burn rate, debt maturity, insider buying, adviser appointment patterns, capital structure stress, sector raise clustering. Use ticker ", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol or \"all\" for market-wide", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal Flow Prediction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/adviser-market-share": { "get": { "operationId": "listAdviserMarketShare", "summary": "Adviser Market Share", "description": "Annual and quarterly league tables showing adviser market share by deal count and value. Includes historical trends, sector specialization, and new entrant tracking.", "tags": [ "Corporate Actions" ], "x-tier": "free", "responses": { "200": { "description": "Adviser Market Share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deal-conflicts/{ticker}": { "get": { "operationId": "getDealConflict", "summary": "Deal Conflicts", "description": "Cross-platform conflict detection for deal advisers. Detects 4 conflict types: auditor independence (adviser firm also audits the company), director cross-board (director sits on both issuer and adviser firm boards), MP interest overlap, and councillor interest overlap. Use ticker ", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol or \"all\" for market-wide", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal Conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/investor-qa/{ticker}": { "get": { "operationId": "simulateInvestorQA", "summary": "Investor Q&A Simulator", "description": "Generate 10 tough investor questions with data-backed suggested responses for IR teams. Aggregates IR Dashboard (15 sources), Management Credibility, Earnings Surprise, financial metrics, peer comparison, insider activity, and sentiment. Questions categorised by difficulty (standard/tough/hostile) and risk level. ~$0.01-0.03/call.", "tags": [ "IR Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investor Q&A Simulation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/management-credibility/{ticker}": { "get": { "operationId": "getManagementCredibility", "summary": "Management Credibility", "description": "Composite 0-100 management credibility score measuring how trustworthy forward guidance is. Based on 4 weighted factors: guidance accuracy (40%), tone consistency (25%), insider trading alignment (20%), and guidance transparency (15%).", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Management Credibility", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/volume-anomalies": { "get": { "operationId": "listVolumeAnomalies", "summary": "Volume Anomalies", "description": "Z-score based volume anomaly detection for NZX stocks. Identifies three types: spikes (single-day z-score above 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.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Filter to a single NZX ticker (e.g. FPH)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Number of days to scan (default: 30, max: 365)", "schema": { "type": "number" } }, { "name": "min_zscore", "in": "query", "required": false, "description": "Minimum z-score threshold (default: 2.0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Volume Anomalies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/metrics": { "get": { "operationId": "listMetrics", "summary": "Financial Metrics", "description": "41 financial ratios across profitability, leverage, cash flow, dividends, growth, valuation. List or per-ticker detail.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "sector", "in": "query", "required": false, "description": "Filter by sector", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by any ratio (e.g., pe_ratio, roe, dividend_yield)", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Sort direction: asc or desc", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year or range", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Financial Metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/metrics/{ticker}": { "get": { "operationId": "getMetric", "summary": "Metrics Detail", "description": "Detailed financial metrics for a company — snapshot with live valuation, or full historical mode.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year or range", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metrics Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/dividends/{ticker}": { "get": { "operationId": "getDividend", "summary": "Dividends", "description": "Per-dividend records with ex-dates, DPS, imputation %, DRP status. Dividend Safety Score (0-100), Forward Cut Probability, payout ratio trend with sector benchmarks.", "tags": [ "Dividends" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year or range", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter: final, interim, special", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dividends", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/technical-signals/{ticker}": { "get": { "operationId": "getTechnicalSignal", "summary": "Technical Signals", "description": "SMA-50/100/200, RSI-14, golden/death cross, 52-week range, volume ratios. Updated daily.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Technical Signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/performance/{ticker}": { "get": { "operationId": "getPerformance", "summary": "Performance Metrics", "description": "Returns (1D-5Y), alpha vs NZX50, volatility, 52-week range, market cap.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Performance Metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/esg/{ticker}": { "get": { "operationId": "getEsg", "summary": "ESG Data", "description": "ESG metrics — emissions (scope 1/2/3), diversity (gender, ethnicity, pay gap), safety, reporting standards.", "tags": [ "ESG" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ESG Data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/esg/{ticker}/xbrl": { "get": { "operationId": "getEsgXbrl", "summary": "ESG iXBRL Climate Disclosure", "description": "Machine-readable NZ Climate Standards (NZ CS 1-3) tagged ESG data. Emissions (Scope 1/2/3), diversity, safety, reporting frameworks. XRB Aotearoa taxonomy.", "tags": [ "ESG" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year (default: latest)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Output format: html (iXBRL document), json (structured facts), llm (token-optimized)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ESG iXBRL Climate Disclosure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/climate-gap-analysis/{ticker}": { "get": { "operationId": "getClimateGapAnalysi", "summary": "Climate Standards Gap Analysis", "description": "NZ XRB Climate Standards (NZ CS 1-4) gap analysis — 23 requirements assessed with status (met/partial/gap), evidence, and recommendations. Identifies mandatory Climate Reporting Entities.", "tags": [ "ESG" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Climate Standards Gap Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/esg-disclosure-gap/{ticker}": { "get": { "operationId": "getEsgDisclosureGap", "summary": "ESG Disclosure Gap Analyzer", "description": "Multi-framework ESG disclosure gap analysis — TCFD (11 recs), ISSB/IFRS S2, and NZ XRB Climate Standards. Per-framework scores, requirement-level gaps, and overall readiness.", "tags": [ "ESG" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "framework", "in": "query", "required": false, "description": "Filter: tcfd, issb, nzcs, or all (default: all)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ESG Disclosure Gap Analyzer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/executive-compensation/{ticker}": { "get": { "operationId": "getExecutiveCompensation", "summary": "Executive Compensation", "description": "CEO/CFO pay — base salary, STI, LTI, total compensation, shares granted.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year filter", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Executive Compensation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/shareholders/{ticker}": { "get": { "operationId": "getShareholder", "summary": "Shareholders", "description": "Top 20 shareholders with ownership concentration metrics (HHI index), holder type classification (nominee/company/individual/trust/fund), year-over-year ownership changes. 8,594 records across 101 issuers with multi-year history (2010-2026). Includes substantial holders (5%+) in response.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year filter (e.g. 2025)", "schema": { "type": "string" } }, { "name": "all", "in": "query", "required": false, "description": "Return all years of shareholder data", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Shareholders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/substantial-holders/{ticker}": { "get": { "operationId": "getSubstantialHolder", "summary": "Substantial Holders", "description": "~267 substantial shareholders (5%+ voting rights) from NZX disclosure notices. Entity name/type, voting rights %, shares held, director/executive flags, disclosure dates, threshold crossing history. Supports ?include_ceased=true for former holders.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "include_ceased", "in": "query", "required": false, "description": "Include former holders who dropped below 5%", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Substantial Holders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/substantial-holders/{ticker}/notices": { "get": { "operationId": "getSubstantialHolderNotices", "summary": "SPH Notices", "description": "9,704 classified SHINTR announcements. Substantial holder notices with holder name, type, percentage, direction (increase/decrease/initial/ceased), and fund manager cross-reference. Real-time ownership change signals between semi-annual filings.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "holder", "in": "query", "required": false, "description": "Filter by holder name", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Filter: increase, decrease, initial, ceased, change", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SPH Notices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/beneficial-ownership/{ticker}": { "get": { "operationId": "getBeneficialOwnership", "summary": "Beneficial Ownership", "description": "Reconstructed beneficial ownership intelligence. Cross-references top-20 shareholder registers with ETF/fund holdings and custodian mappings to identify who is behind nominee/custodian entries. Returns direct holders, nominee breakdowns with identified fund managers, fund holdings summary, and substantial holders.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficial Ownership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agm-resolutions/{ticker}": { "get": { "operationId": "getAgmResolution", "summary": "AGM Resolutions", "description": "1,662 AGM resolutions with voting data. Identify failed resolutions, contested directors, activism.", "tags": [ "Proxy Advisory" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Year filter (2023-2025)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AGM Resolutions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agm-speeches/{ticker}": { "get": { "operationId": "getAgmSpeeches", "summary": "AGM Speech Analysis", "description": "NLP analysis of Chair/CEO AGM speeches — Language Intelligence Score (0-100), sentiment, hedging, complexity.", "tags": [ "Proxy Advisory" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Year filter", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AGM Speech Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/kiwisaver-holdings/{ticker}": { "get": { "operationId": "getKiwisaverHolding", "summary": "KiwiSaver Holdings", "description": "Which KiwiSaver funds hold this NZX stock. 6,872 holdings across 370 funds.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "KiwiSaver Holdings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/screener": { "get": { "operationId": "listScreener", "summary": "Financial Screener", "description": "Screen 131 NZX stocks across 200+ metrics. Smart presets, custom filters, sorting. The ", "tags": [ "Screener" ], "x-tier": "free", "parameters": [ { "name": "preset", "in": "query", "required": false, "description": "Smart preset: value, growth, quality, oversold, overbought, golden_cross, below_200ma, death_cross, dividend_risk, dividend_aristocrats, low_volatility, turnaround, small_cap_gems, insider_buying, capital_raise, ceo_pay_failure, governance_laggards, income_portfolio, conservative_growth, esg_compliant", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search by company name or ticker", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by any of 90 columns (e.g., rsi_14, pe_ratio, grs_score, return_1y, sentiment_score, next_results_days)", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Sort direction: asc or desc (default: desc)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year (default: latest per company)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 500 (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Financial Screener", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/iod-designations": { "get": { "operationId": "listIodDesignations", "summary": "IoD Designations", "description": "Institute of Directors designated directors on NZX boards. CFInstD, CMInstD, CDir, MInstD designations with current board seats and summary statistics.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "designation", "in": "query", "required": false, "description": "Filter by designation: CFInstD, CMInstD, CDir, MInstD", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Search by director name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "IoD Designations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/skills-matrix/{ticker}": { "get": { "operationId": "getSkillsMatrix", "summary": "Board Skills Matrix", "description": "Board skills matrix for an NZX company. 12 skill categories (IoD NZ, ASX CGC, AICD aligned) with proficiency levels per director, gap analysis, and diversity score.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, MEL)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Skills Matrix", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-gap-report/{ticker}": { "get": { "operationId": "getBoardGapReport", "summary": "Board Gap Intelligence Report", "description": "Comprehensive board gap analysis for an NZX company. Includes current board composition, skills gap assessment, ideal candidate profile, fee benchmarking, and peer comparison. Uses director skills matrix, remuneration history, and sector peer data.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, MEL)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Gap Intelligence Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-gap-report/{ticker}/pdf": { "get": { "operationId": "getBoardGapReportPdf", "summary": "Board Gap Report PDF", "description": "Print-optimized board gap intelligence report with white-label branding support. Suitable for board packs and governance reviews.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, MEL)", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "White-label brand name for report header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Gap Report PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-vacancies": { "get": { "operationId": "listBoardVacancies", "summary": "Board Vacancies", "description": "Current board vacancies aggregated from Appoint Better Boards and IoD NZ. Filterable by source, sector, region, and skills required.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "source", "in": "query", "required": false, "description": "Filter by source: appoint, iod, or all (default: all)", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector (e.g., Healthcare, Technology)", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Filter by region (e.g., Auckland, Wellington, Canterbury)", "schema": { "type": "string" } }, { "name": "skills", "in": "query", "required": false, "description": "Comma-separated skills to match (e.g., finance,governance)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Board Vacancies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/credit-ratings/{ticker}": { "get": { "operationId": "getCreditRating", "summary": "Credit Ratings", "description": "Credit rating history from S&P, Moody\\", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., ANZ, MEL, SPK)", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Filter by action: affirmed, upgraded, downgraded, assigned, withdrawn", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Credit Ratings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/capital-raises/{ticker}": { "get": { "operationId": "getCapitalRaises", "summary": "Capital Raises", "description": "Structured capital raise history: placements, rights issues, SPPs, IPOs, bonds, buybacks, DRPs. ~11,700 events across 131 issuers.", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FBU, RYM)", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Comma-separated raise types: placement, rights_issue, spp, ipo, bond, buyback, drp, options_exercise, employee_scheme, conversion", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Capital Raises", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/capital-raise-sentiment/{ticker}": { "get": { "operationId": "getCapitalRaiseSentiment", "summary": "Capital Raise Sentiment", "description": "Classifies each capital raise as ", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, FBU)", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Comma-separated raise types: placement, rights_issue, spp, ipo, bond", "schema": { "type": "string" } }, { "name": "context", "in": "query", "required": false, "description": "Filter by classification: strength, neutral, desperation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Capital Raise Sentiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/segments/{ticker}": { "get": { "operationId": "getSegment", "summary": "Revenue Segments", "description": "Revenue segment breakdown for multi-segment NZX companies (IFRS 8 Operating Segments). Operating, geographic, and product segments with revenue, operating profit, assets, and revenue percentage. Extracted from annual report PDFs via AI.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Segment type: operating, geographic, product", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 50)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Revenue Segments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/takeovers/{ticker}": { "get": { "operationId": "getTakeover", "summary": "Takeovers & M&A", "description": "Structured M&A and takeover activity: takeover offers, mergers, schemes of arrangement, compulsory acquisitions, asset acquisitions. 313 deals across 51 issuers (2017-2026). Deal details include acquirer, offer price, total value, premium, acceptance %, status, and timeline.", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated: announced, conditional, unconditional, completed, withdrawn, failed", "schema": { "type": "string" } }, { "name": "deal_type", "in": "query", "required": false, "description": "Comma-separated: takeover_offer, merger, scheme_of_arrangement, compulsory_acquisition, acquisition", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 50)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Takeovers & M&A", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/signals": { "get": { "operationId": "listSignals", "summary": "Market Intelligence Feed", "description": "Unified stream of all NZX market events: insider trades, capital raises, dividends, earnings releases, AGM results (failed/contentious), director appointments/resignations, governance score changes, technical signals (golden/death cross, RSI extremes), credit rating changes, auditor changes, and takeover/M&A activity. 11 signal types. Sorted by date descending. The ", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Comma-separated: insider_trade, capital_raise, dividend, earnings, agm_result, director_change, grs_change, technical_signal, credit_rating, audit_change, takeover", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback days (default 180). Use 7 for this week, 1 for today", "schema": { "type": "number" } }, { "name": "significance", "in": "query", "required": false, "description": "Filter: high, medium, low", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 50, max 500)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Market Intelligence Feed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-report/{slug}": { "get": { "operationId": "getDirectorReport", "summary": "Director Due Diligence Report", "description": "Comprehensive due diligence report for any NZX director. Aggregates all board positions, remuneration, insider trading, AGM voting record, governance contribution, performance during tenure, overboarding assessment, and risk flags into a single structured response. Designed for executive search firms, law firms, and nominating committees.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Director slug (e.g., \"joan-withers\", \"mark-cross\")", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Director Due Diligence Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/kyc-screening/{slug}": { "get": { "operationId": "getKycScreening", "summary": "KYC/AML Director Screening", "description": "Automated KYC/AML screening — cross-references director against 8 risk databases (regulatory actions, court cases, professional disciplinary, prohibited directors, ICIJ offshore leaks, political donors, MP interests, insolvency). Returns risk score 0-100, risk rating, PEP status, detailed flags.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Director slug (e.g. joan-withers)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "KYC/AML Director Screening", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxy-report/{ticker}": { "get": { "operationId": "getProxyReport", "summary": "Proxy Advisory Report", "description": "Automated voting recommendations for a company\\", "tags": [ "Proxy Advisory" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } }, { "name": "meeting_id", "in": "query", "required": false, "description": "Specific meeting ID", "schema": { "type": "string" } }, { "name": "policy", "in": "query", "required": false, "description": "Base64-encoded JSON voting policy to override default thresholds. See /proxy/policy for the editor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proxy Advisory Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxy-report/{ticker}/pdf": { "get": { "operationId": "getProxyReportPdf", "summary": "Proxy Advisory Report (PDF)", "description": "Print-optimized HTML version of the proxy advisory report, designed for browser ", "tags": [ "Proxy Advisory" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } }, { "name": "policy", "in": "query", "required": false, "description": "Base64-encoded JSON voting policy to override default thresholds", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proxy Advisory Report (PDF)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/anomalies": { "get": { "operationId": "listAnomalies", "summary": "Market Anomaly Detection", "description": "Early warning system scanning all NZX companies for unusual patterns across 7 categories (insider trading, governance, financial, market, AGM, corporate, sentiment). Detects 16 anomaly types: insider clusters, insider exodus, conviction shifts, GRS deterioration, director exodus, audit changes, dividend cut risk, capital raise patterns, earnings concerns, first-time risk language, technical breakdowns/breakouts, AGM revolts, active takeovers, sentiment-market disagreements, and buried risk detection. Returns anomalies sorted by severity.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Lookback period in days (default 180)", "schema": { "type": "number" } }, { "name": "category", "in": "query", "required": false, "description": "Filter: insider, governance, financial, market, agm, corporate, sentiment", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "Filter: critical, warning, watch", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market Anomaly Detection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/reports/{ticker}": { "get": { "operationId": "getReport", "summary": "Annual & Interim Reports", "description": "Report URLs, financial year, extraction status for annual and interim reports. Includes report dates and sources.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter: annual, interim", "schema": { "type": "string" } }, { "name": "extracted", "in": "query", "required": false, "description": "Filter: true, false", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Annual & Interim Reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/annual-reports/{ticker}": { "get": { "operationId": "getAnnualReport", "summary": "Annual Reports (alias)", "description": "Alias for /reports/{ticker}. Returns annual and interim report URLs with financial year coverage and extraction status. 2,032 reports across 131 issuers (FY2010-2025).", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter: annual, interim", "schema": { "type": "string" } }, { "name": "extracted", "in": "query", "required": false, "description": "Filter: true, false", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Annual Reports (alias)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/audit-changes": { "get": { "operationId": "listAuditChanges", "summary": "Auditor Changes", "description": "Auditor appointment, resignation, and change history for NZX companies. Tracks Big Four (PwC, KPMG, Deloitte, EY) movements.", "tags": [ "Corporate Actions" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Filter by NZX ticker symbol", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Filter: appointed, resigned, changed, reappointed", "schema": { "type": "string" } }, { "name": "auditor", "in": "query", "required": false, "description": "Filter by auditor name (partial match)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auditor Changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-changes/{ticker}": { "get": { "operationId": "getBoardChange", "summary": "Board Changes", "description": "Director appointments, resignations, retirements, and other board composition changes.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Filter: appointed, resigned, retired, removed, elected, re-elected", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Board Changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-report/{ticker}": { "get": { "operationId": "getBoardReport", "summary": "Board Composition Report", "description": "Comprehensive board composition analytics report. Independence, diversity, tenure, skills matrix, attendance, remuneration, succession risk, turnover, and peer benchmarks. JSON or PDF.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Composition Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounting-quality/{ticker}": { "get": { "operationId": "getAccountingQuality", "summary": "Accounting Quality Scores", "description": "Accounting quality analysis for an NZX company. Includes Beneish M-score (earnings manipulation probability), Piotroski F-score (financial strength 0-9), Altman Z-score (bankruptcy risk), interest coverage ratio, and current ratio. 129 issuers scored.", "tags": [ "Financials" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., \"FPH\", \"AIR\")", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting Quality Scores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/downloads/{dataset}": { "get": { "operationId": "getDownload", "summary": "Bulk Data Downloads", "description": "Enterprise-tier bulk data downloads in CSV or JSON format. 13 datasets: financials, balance-sheets, cash-flows, financial-ratios, directors, remuneration, insider-trades, dividends, governance, capital-raises, agm-resolutions, esg-metrics, shareholders. Supports date-based snapshots and company filtering.", "tags": [ "Export" ], "x-tier": "free", "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name (e.g. financials, directors, governance)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Output format: json (default), csv", "schema": { "type": "string" } }, { "name": "ticker", "in": "query", "required": false, "description": "Filter by ticker(s), comma-separated (e.g. AIR,FPH,MEL)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD) for date-ordered datasets (insider-trades, dividends, capital-raises, shareholders)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD) for date-ordered datasets", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector(s), comma-separated (e.g. Utilities,Healthcare)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bulk Data Downloads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/semantic-search": { "get": { "operationId": "listSemanticSearch", "summary": "Semantic Search", "description": "AI-powered search across 64,000+ NZX announcements. Supports 3 modes: keyword (BM25 FTS), semantic (pgvector cosine similarity), and hybrid (RRF fusion of both). Optional Cohere reranking for maximum relevance.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (natural language)", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Search mode: keyword, semantic (default), hybrid", "schema": { "type": "string" } }, { "name": "rerank", "in": "query", "required": false, "description": "Enable Cohere reranking (default false)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "issuer_id", "in": "query", "required": false, "description": "Filter by company ID", "schema": { "type": "number" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by announcement type (e.g. FLLYR, HALFYR)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 20)", "schema": { "type": "number" } }, { "name": "threshold", "in": "query", "required": false, "description": "Min similarity score 0-1 (default 0.5)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Semantic Search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/risk-language/{ticker}": { "get": { "operationId": "getRiskLanguage", "summary": "Risk Language Scores", "description": "Pre-computed risk language analysis 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, category breakdown, critical flags, first-time detections, and yearly trend.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., \"FBU\", \"AIR\")", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risk Language Scores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/keyword-trends": { "get": { "operationId": "listKeywordTrends", "summary": "Keyword Trend Analysis", "description": "Search any keyword or phrase across 64,000+ NZX company announcements and see how often it appears over time. Returns frequency by year, sector, and top companies. Like Google Trends for corporate filings.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "keyword", "in": "query", "required": true, "description": "Keyword or phrase to search (min 2 chars, max 100)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keyword Trend Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/announcement-alerts": { "get": { "operationId": "listAnnouncementAlerts", "summary": "List Announcement Alert Rules", "description": "List all announcement alert rules for the authenticated user. Rules match NZX announcements by keywords, tickers, sectors, and announcement types, then deliver via email or webhook. Uses parseCursorPagination() + buildCursorMeta() helpers internally.", "tags": [ "Market Intelligence" ], "x-tier": "free", "responses": { "200": { "description": "List Announcement Alert Rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAnnouncementAlerts", "summary": "Create Announcement Alert Rule", "description": "Create a new announcement alert rule. When matching announcements are published, notifications are delivered via your chosen method. keyword_match_mode controls whether any or all keywords must match.", "tags": [ "Market Intelligence" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable rule name" }, "keywords": { "type": "string", "description": "Keywords or phrases to match in announcements" }, "tickers": { "type": "string", "description": "NZX tickers to monitor (empty = all)" }, "sectors": { "type": "string", "description": "Sectors to monitor (empty = all)" }, "announcement_types": { "type": "string", "description": "Announcement types to monitor (e.g. FLLYR, GENERAL, SHINTR)" }, "is_active": { "type": "string", "enum": [ "true", "false" ], "description": "Whether the rule is active (default: true)" } }, "required": [ "name", "keywords" ] } } } }, "responses": { "200": { "description": "Create Announcement Alert Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/announcement-alerts/{id}": { "patch": { "operationId": "patchAnnouncementAlerts", "summary": "Update Announcement Alert Rule", "description": "Update an existing announcement alert rule. Send only the fields you want to change.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Alert rule ID (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update Announcement Alert Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAnnouncementAlerts", "summary": "Delete Announcement Alert Rule", "description": "Permanently delete an announcement alert rule and all associated match history.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Alert rule ID (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete Announcement Alert Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/announcement-alerts/{id}/matches": { "get": { "operationId": "getAnnouncementAlertMatches", "summary": "List Announcement Alert Matches", "description": "List announcements that matched a specific alert rule. Returns matched announcements with the keywords that triggered the match.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Alert rule ID (path parameter)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Announcement Alert Matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/alerts/subscriptions": { "get": { "operationId": "getAlertsSubscriptions", "summary": "List Alert Subscriptions", "description": "List all alert subscriptions for the authenticated user. Also supports POST to create a new subscription. Subscriptions filter market signals and anomalies by tickers, sectors, signal types, anomaly categories, and severity — then deliver via webhook or email. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "List Alert Subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAlertsSubscriptions", "summary": "Create Alert Subscription", "description": "Create a new alert subscription. Configure which signal types (11 types: insider_trade, capital_raise, dividend, earnings, agm_result, director_change, grs_change, technical_signal, credit_rating, audit_change, takeover) and anomaly categories (insider, governance, financial, market, agm, corporate) to monitor. Filter by tickers and/or sectors. Choose webhook or email delivery with realtime, daily, or weekly frequency. Webhook payloads are signed with HMAC-SHA256. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable subscription name" }, "signal_types": { "type": "string", "description": "Signal types to include (11 available)" }, "anomaly_categories": { "type": "string", "description": "Anomaly categories to include (6 available)" }, "min_severity": { "type": "string", "description": "Minimum severity: low, medium, high, critical (default: low)" }, "delivery_method": { "type": "string", "description": "Delivery method: webhook or email" }, "delivery_frequency": { "type": "string", "description": "Frequency: realtime, daily, or weekly" }, "webhook_url": { "type": "string", "description": "Webhook endpoint URL (required if delivery_method is webhook)" }, "webhook_secret": { "type": "string", "description": "Secret for HMAC-SHA256 signing of webhook payloads" }, "email_address": { "type": "string", "description": "Email address (required if delivery_method is email)" } }, "required": [ "name", "signal_types", "delivery_method", "delivery_frequency" ] } } } }, "responses": { "200": { "description": "Create Alert Subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/alerts/test": { "post": { "operationId": "testAlertsTest", "summary": "Test Webhook Delivery", "description": "Send a test alert payload to a subscription\\", "tags": [ "Alerts" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "number", "description": "ID of the subscription to test" } }, "required": [ "subscription_id" ] } } } }, "responses": { "200": { "description": "Test Webhook Delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List Webhook Subscriptions", "description": "List all webhook subscriptions for the authenticated user. Each subscription includes name, URL, event type filters (tickers, sectors, signal types), and active status. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "List Webhook Subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createWebhooks", "summary": "Create Webhook", "description": "Create a new webhook subscription with name, URL, and optional filters for tickers, sectors, and signal types. Payloads are signed with HMAC-SHA256. Supports 12 market event types (insider_trade, capital_raise, dividend, earnings, agm_result, director_change, grs_change, technical_signal, credit_rating, audit_change, takeover, board_event) and 6 board event types. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable webhook name" }, "url": { "type": "string", "description": "Webhook endpoint URL (must be HTTPS)" }, "filters": { "type": "string", "description": "Optional filters: { tickers: string[], sectors: string[], signal_types: string[] }" } }, "required": [ "name", "url" ] } } } }, "responses": { "200": { "description": "Create Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}": { "put": { "operationId": "updateWebhooks", "summary": "Update Webhook", "description": "Update an existing webhook subscription. Supports partial updates — only include the fields you want to change (name, url, filters, is_active). Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteWebhooks", "summary": "Delete Webhook", "description": "Permanently delete a webhook subscription and its delivery history. This action cannot be undone. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/history": { "get": { "operationId": "getWebhookHistory", "summary": "Webhook Delivery History", "description": "View delivery history for a specific webhook subscription. Shows success/failure status, HTTP response codes, and timestamps. Paginated. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default: 50)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (default: 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Webhook Delivery History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhooksTest", "summary": "Test Webhook", "description": "Send a test payload to a webhook endpoint to verify it is reachable and correctly handles HMAC-SHA256 signed payloads. Returns delivery status. Enterprise tier required.", "tags": [ "Alerts" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/auth": { "get": { "operationId": "getZapierAuth", "summary": "Zapier Auth Test", "description": "Verify API key during Zapier connection setup. Returns authenticated user email, tier, and key name. Used by Zapier during ", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "Zapier Auth Test", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/triggers/announcements": { "get": { "operationId": "getZapierTriggersAnnouncements", "summary": "Zapier: New Announcement", "description": "Polling trigger for Zapier. Returns recent NZX announcements sorted newest first. Zapier deduplicates by id field. Filter by ticker, sector, announcement type, and lookback period.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Comma-separated tickers (e.g., FPH,AIR)", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Sector filter", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Announcement type (e.g., SHINTR, FLLYR)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback days (default: 7, max: 30)", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 50, max: 100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Zapier: New Announcement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/triggers/insider-trades": { "get": { "operationId": "getZapierTriggersInsiderTrades", "summary": "Zapier: New Insider Trade", "description": "Polling trigger for Zapier. Returns recent director share transactions sorted newest first. Includes director name, transaction type, shares, price, and total value.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Comma-separated tickers", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Transaction type (Purchase, Sale, Exercise)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback days (default: 30, max: 90)", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 50, max: 100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Zapier: New Insider Trade", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/triggers/grs-changes": { "get": { "operationId": "getZapierTriggersGrsChanges", "summary": "Zapier: GRS Score Change", "description": "Polling trigger for Zapier. Returns companies where Governance Risk Score changed by at least min_change points. Compares latest two calculations per issuer.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Comma-separated tickers", "schema": { "type": "string" } }, { "name": "min_change", "in": "query", "required": false, "description": "Minimum absolute change (default: 5)", "schema": { "type": "number" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback days (default: 14, max: 60)", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 50, max: 100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Zapier: GRS Score Change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/hooks": { "post": { "operationId": "createZapierHooks", "summary": "Zapier: Subscribe REST Hook", "description": "Register a REST Hook for real-time event push. Zapier calls this when a Zap is turned on. Events are pushed to target_url during the cron dispatch cycle. Auto-deactivates on 410 Gone.", "tags": [ "Alerts" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "Zapier webhook receiver URL" }, "event_type": { "type": "string", "description": "Event type: announcement, insider_trade, grs_change, dividend, capital_raise, director_change, earnings, composite_signal" }, "tickers": { "type": "string", "description": "Ticker filter (empty = all)" }, "sectors": { "type": "string", "description": "Sector filter (empty = all)" } }, "required": [ "target_url", "event_type" ] } } } }, "responses": { "200": { "description": "Zapier: Subscribe REST Hook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/zapier/hooks/{id}": { "delete": { "operationId": "deleteZapierHooks", "summary": "Zapier: Unsubscribe REST Hook", "description": "Remove a REST Hook subscription. Zapier calls this when a Zap is turned off.", "tags": [ "Alerts" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hook ID (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Zapier: Unsubscribe REST Hook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/user-alerts": { "get": { "operationId": "listUserAlerts", "summary": "List User Alerts", "description": "List all alert subscriptions for the logged-in user. Session-authenticated (cookie-based, not API key). Returns alert name, tickers, signal types, severity, and active status.", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "List User Alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createUserAlerts", "summary": "Create User Alert", "description": "Create a new alert subscription for the logged-in user. Supports 12 signal types, ticker filtering, severity levels, and email delivery. Maximum 20 alerts per user. Session-authenticated.", "tags": [ "Alerts" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable alert name" }, "tickers": { "type": "string", "description": "NZX ticker symbols (empty = all companies)" }, "signal_types": { "type": "string", "description": "Event types to monitor (empty = all types)" }, "min_severity": { "type": "string", "description": "Minimum severity: low, medium, high, critical (default: medium)" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Create User Alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stewardship-reports": { "get": { "operationId": "listStewardshipReports", "summary": "List Stewardship Reports", "description": "List all FMA-compliant stewardship/voting-record reports for the authenticated user. Each report contains per-company proxy analysis, vote summaries, and category breakdowns. Enterprise tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "responses": { "200": { "description": "List Stewardship Reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createStewardshipReports", "summary": "Generate Stewardship Report", "description": "Generate a new FMA-compliant stewardship report. Runs the proxy advisory engine across all specified tickers for the given period, producing per-company resolution analysis with vote recommendations. Enterprise tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tickers": { "type": "string", "description": "Array of NZX ticker symbols (max 100)" }, "policy_id": { "type": "string", "description": "Voting policy preset ID (default: nzxplorer)" } }, "required": [ "tickers" ] } } } }, "responses": { "200": { "description": "Generate Stewardship Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stewardship-reports/{id}": { "get": { "operationId": "getStewardshipReport", "summary": "Stewardship Report Detail", "description": "Get a single stewardship report with full report_data including per-company resolution analysis, vote recommendations, and the policy used. Enterprise tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Report ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stewardship Report Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stewardship-reports/{id}/pdf": { "get": { "operationId": "getStewardshipReportPdf", "summary": "Stewardship Report PDF", "description": "Print-optimized HTML version of a stewardship report. Open in browser and use ", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Report ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stewardship Report PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/voting-policies": { "get": { "operationId": "listVotingPolicies", "summary": "List Voting Policies", "description": "List all custom voting policies for the authenticated user. Policies define threshold overrides for the proxy advisory engine (board independence, remuneration caps, tenure limits, etc.). Enterprise or Institutional tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "responses": { "200": { "description": "List Voting Policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createVotingPolicies", "summary": "Create Voting Policy", "description": "Create a new custom voting policy with threshold overrides. The policy JSONB must include at minimum board_independence_min (number). Optionally set base_preset to inherit defaults from a built-in preset (nzxplorer, conservative, progressive, permissive, iss_nz, nz_super, russell_nz, vanguard_aunz). Enterprise or Institutional tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Policy name" }, "description": { "type": "string", "description": "Policy description" }, "base_preset": { "type": "string", "description": "Base preset ID to inherit defaults from" }, "policy": { "type": "string", "description": "Policy threshold overrides (must include board_independence_min)" }, "is_default": { "type": "string", "enum": [ "true", "false" ], "description": "Set as default policy for this user" } }, "required": [ "name", "policy" ] } } } }, "responses": { "200": { "description": "Create Voting Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/voting-policies/{id}": { "get": { "operationId": "getVotingPolicy", "summary": "Voting Policy Detail", "description": "Get a single voting policy by ID. Enterprise or Institutional tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Voting Policy Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchVotingPolicies", "summary": "Update Voting Policy", "description": "Update an existing voting policy. Only provided fields are changed. Enterprise or Institutional tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated policy name" }, "description": { "type": "string", "description": "Updated description" }, "policy": { "type": "string", "description": "Updated policy thresholds" }, "is_default": { "type": "string", "enum": [ "true", "false" ], "description": "Set as default policy" } } } } } }, "responses": { "200": { "description": "Update Voting Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteVotingPolicies", "summary": "Delete Voting Policy", "description": "Delete a voting policy. Cannot delete a policy that is referenced by stewardship reports. Enterprise or Institutional tier required.", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete Voting Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/widgets/{type}": { "get": { "operationId": "getWidget", "summary": "Embeddable Widgets", "description": "Pre-built data widgets for embedding on third-party websites. 8 widget types: price-card, governance-badge, dividend-history, insider-activity, financials-summary, company-overview, sector-heatmap, portfolio-summary. Pro+ tier required.", "tags": [ "Widgets" ], "x-tier": "free", "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Widget type: price-card, governance-badge, dividend-history, insider-activity, financials-summary, company-overview, sector-heatmap, portfolio-summary", "schema": { "type": "string" } }, { "name": "ticker", "in": "query", "required": false, "description": "NZX ticker symbol (required for all types except sector-heatmap and portfolio-summary)", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Performance period for sector-heatmap: 1w (default) or 1m", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embeddable Widgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/portfolio/import-csv": { "post": { "operationId": "importPortfolioImportCsv", "summary": "Portfolio CSV Import", "description": "Import portfolio holdings from a broker CSV export. Auto-detects Sharesies, Sharesight, and Hatch formats. Cleans tickers (.NZ suffix, NZX: prefix), validates 2-5 char codes. Use merge=true to add new tickers without replacing existing holdings.", "tags": [ "Widgets" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "CSV file contents as a string (header + data rows)" }, "platform": { "type": "string", "description": "Force platform: sharesies, sharesight, hatch, auto (default: auto-detect from headers)" }, "merge": { "type": "string", "enum": [ "true", "false" ], "description": "If true, add new tickers only (skip existing). Default: false (replace all)" } }, "required": [ "csv" ] } } } }, "responses": { "200": { "description": "Portfolio CSV Import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/widgets/portfolio-summary": { "get": { "operationId": "getWidgetsPortfolioSummary", "summary": "Portfolio Summary Widget", "description": "Embeddable portfolio summary widget. Returns HTML snippet or JSON data for your portfolio holdings, P&L, governance scores, and sector exposure. Use format=html for iframe embedding on blogs/sites.", "tags": [ "Widgets" ], "x-tier": "free", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Response format: html (default) or json", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "required": false, "description": "Widget theme: light (default) or dark", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portfolio Summary Widget", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sector-heatmap": { "get": { "operationId": "listSectorHeatmap", "summary": "Sector Heatmap", "description": "NZX market sectors aggregated by market cap with average weekly or monthly performance. Supports drill-down to individual companies within a sector via ?sector= filter.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Performance period: 1w (default) or 1m", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Drill down to a specific sector for per-company data", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sector Heatmap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-briefing/{ticker}": { "get": { "operationId": "getBoardBriefing", "summary": "Board Briefing", "description": "Comprehensive board meeting preparation briefing with governance scores, insider activity, announcements with sentiment, dividend analysis, financial health, peer comparison, AGM status, and board changes. Aggregates 10+ data sources into a single executive-ready report for directors, company secretaries, and institutional investors.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-effectiveness/{ticker}": { "get": { "operationId": "getBoardEffectivenes", "summary": "Board Effectiveness Dashboard", "description": "Comprehensive board health assessment for any NZX-listed company. Returns composition analysis (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. Designed for board chairs and governance professionals. Supports ?format=llm for Copilot-friendly text output.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Effectiveness Dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/factor-model": { "get": { "operationId": "listFactorModel", "summary": "NZ Equity Factor Model", "description": "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. Inspired by Fama-French and Bloomberg Factor Model.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "sector", "in": "query", "required": false, "description": "Filter by sector (e.g., Healthcare, Property)", "schema": { "type": "string" } }, { "name": "factor", "in": "query", "required": false, "description": "Sort by factor: value, growth, profitability, momentum, dividends, governance", "schema": { "type": "string" } }, { "name": "grade", "in": "query", "required": false, "description": "Filter by composite grade (e.g., A,B)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Limit results (default: all)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "NZ Equity Factor Model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-benchmark/{ticker}": { "get": { "operationId": "getBoardBenchmark", "summary": "Board Evaluation Benchmarking", "description": "Quantitative board benchmarking vs sector and market-cap peers across 6 dimensions: board size, independence ratio, gender diversity, skills coverage, meeting frequency, and fee levels. Includes percentile rankings, P25/P75 ranges, 3-year trend, and overall assessment with strengths and improvements.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Evaluation Benchmarking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/chair-ceo-alignment/{ticker}": { "get": { "operationId": "getChairCeoAlignment", "summary": "Chair vs CEO Communication Alignment", "description": "Compares Chair and CEO Language Intelligence Scores (LIS), sentiment, conviction, and transparency from AGM speeches. Flags divergence (>10 LIS gap) as a governance signal. Includes historical trend analysis.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chair vs CEO Communication Alignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/government-contracts/{ticker}": { "get": { "operationId": "getGovernmentContract", "summary": "Government Contracts", "description": "Government contracts awarded via GETS — contract history, agencies, values, procurement types", "tags": [ "Governance" ], "x-tier": "pro", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Government Contracts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/hidden-connections/{ticker}": { "get": { "operationId": "getHiddenConnection", "summary": "Hidden Connections", "description": "Hidden connections — private company board overlaps between this company\\", "tags": [ "Governance" ], "x-tier": "pro", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hidden Connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/quarterly-ownership-report": { "post": { "operationId": "createQuarterlyOwnershipReport", "summary": "Quarterly Ownership Report", "description": "Generate a quarterly ownership PDF report for a portfolio of NZX companies. Top 20 shareholders, substantial holders, fund identification, HHI analysis.", "tags": [ "Insider Trades" ], "x-tier": "enterprise", "responses": { "200": { "description": "Quarterly Ownership Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/succession-plan/{ticker}": { "get": { "operationId": "getSuccessionPlan", "summary": "Succession Plan", "description": "Board succession risk assessment — 5-factor risk model, tenure cohorts, skills concentration risks, cliff risk detection, and successor candidates", "tags": [ "Governance" ], "x-tier": "pro", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Succession Plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-questionnaire/{ticker}/{slug}": { "get": { "operationId": "getDirectorQuestionnaire", "summary": "D&O Questionnaire Auto-Fill", "description": "Pre-fills 75-85% of a typical Directors & Officers insurance questionnaire from cross-platform data. Aggregates 15+ data sources: all directorships (NZX + charity + iwi + public sector), insider trades, shareholdings, skills matrix, qualifications, committees, regulatory actions, court cases, professional disciplinary, political connections, career history, and compensation. Designed for board management platforms, company secretaries, and D&O insurance brokers.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH)", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "Director slug from profile URL (e.g., rob-campbell)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "D&O Questionnaire Auto-Fill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deep-research/{ticker}": { "post": { "operationId": "runDeepResearch", "summary": "Deep Research Pipeline", "description": "In-depth AI research pipeline (v2). Deterministic fetch of 35+ proprietary data sources, external validation via NZ media sentiment and web search, then 5 Claude Sonnet analysis phases with cross-referencing, synthesised into a structured report with [S1]-[Sn] source citations. POST streams SSE progress events; GET returns cached report synchronously (24hr TTL). Cost: ~$0.30-0.50/query. Pro+ tier.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "description": "Research template: general (default), investment_thesis, due_diligence, board_meeting" }, "question": { "type": "string", "description": "Optional focus question for the research" } } } } } }, "responses": { "200": { "description": "Deep Research Pipeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deep-research-qa/{ticker}": { "get": { "operationId": "getDeepResearchQa", "summary": "Deep Research QA", "description": "Validate a deep research report against ground-truth NZXplorer data. Cross-checks financial figures (revenue, NPAT), GRS scores, accounting quality (M/F/Z-scores), director counts, ESG data, thesis structure, risk sourcing, and unit consistency. GET validates cached report; POST validates a submitted report body. Returns per-check pass/fail/warn, overall confidence score (0-100), critical failures, and recommendations.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deep Research QA", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-conflicts/{ticker}": { "get": { "operationId": "getDirectorConflict", "summary": "Director Conflicts", "description": "Automated conflict-of-interest detection for directors. Returns cross-directorships (directors on multiple NZX boards), overboarding risk, related entity overlaps (shared charity/public sector roles), and cross-company insider trading flags. Risk-rated summary.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Director Conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/interest-register/{ticker}": { "get": { "operationId": "getInterestRegister", "summary": "Interest Register", "description": "Auto-populated interest register for a company\\", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interest Register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/research/{ticker}": { "get": { "operationId": "getResearch", "summary": "Research Briefing", "description": "AI-powered investment research briefing with narrative synthesis. Assembles 15+ data sources (governance, financials, insider activity, dividends, board composition, earnings, credit ratings, performance, capital raises, announcements with sentiment) and produces a structured briefing with AI-generated executive summary, key strengths, risks, and outlook via Claude Haiku.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } }, { "name": "template", "in": "query", "required": false, "description": "Research template: general (default), investment_thesis, due_diligence, or board_meeting", "schema": { "type": "string" } }, { "name": "focus", "in": "query", "required": false, "description": "Comma-separated focus areas (e.g., dividends,governance)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Research Briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fund-votes/{ticker}": { "get": { "operationId": "getFundVote", "summary": "Fund Manager Votes", "description": "Actual voting records from NZ fund managers (Harbour, Devon, Mint, Fisher, NZ Super Fund) for a specific company. Shows how institutional investors voted on AGM resolutions — FOR, AGAINST, or ABSTAIN — with ISS and management recommendations for comparison.", "tags": [ "Stewardship" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } }, { "name": "fund_manager", "in": "query", "required": false, "description": "Filter by fund manager name (e.g., Harbour, Devon, Mint)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Filter by year (e.g., 2024) or range (e.g., 2023-2025)", "schema": { "type": "string" } }, { "name": "vote", "in": "query", "required": false, "description": "Filter by vote cast: FOR, AGAINST, or ABSTAIN", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fund Manager Votes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sentiment/{ticker}": { "get": { "operationId": "getSentiment", "summary": "Announcement Sentiment", "description": "AI-scored sentiment analysis of company announcements. Returns per-announcement sentiment scores, confidence, hedging levels, buried risks, key topics, and guidance direction. Includes company-level summary with average score and sentiment breakdown.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } }, { "name": "sentiment", "in": "query", "required": false, "description": "Filter by sentiment: positive, negative, neutral, mixed", "schema": { "type": "string" } }, { "name": "hedging", "in": "query", "required": false, "description": "Filter by hedging level: none, low, moderate, heavy", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Announcement Sentiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/mcp/status": { "get": { "operationId": "getMcpStatus", "summary": "MCP Server Status", "description": "Returns the status of connected external MCP servers in the Multi-MCP Copilot integration. Shows which servers are enabled, connected, and what tools they provide. Useful for monitoring and debugging MCP connectivity.", "tags": [ "Copilot" ], "x-tier": "free", "responses": { "200": { "description": "MCP Server Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/regulatory-actions/{ticker}": { "get": { "operationId": "getRegulatoryAction", "summary": "Regulatory Actions", "description": "Returns enforcement actions from FMA, Commerce Commission, NZX, and other regulators for a specific NZX-listed company. Includes penalty amounts, severity ratings, and any prohibited director matches.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. AIR, FPH)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Regulatory Actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/political-connections/{ticker}": { "get": { "operationId": "getPoliticalConnection", "summary": "Political Connections", "description": "MP interests, party donations, and director-donor cross-references for an NZX company. Data from the NZ Parliamentary Register of Interests and Electoral Commission party donation records (2019-2024).", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., SKC, AIR, SAN)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Political Connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/prohibited-directors": { "get": { "operationId": "listProhibitedDirectors", "summary": "Prohibited Directors", "description": "Returns the full list of prohibited/banned directors from the Companies Office register, including any name matches to current NZX directors. A match does not confirm identity.", "tags": [ "Directors" ], "x-tier": "free", "responses": { "200": { "description": "Prohibited Directors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/litigation/{ticker}": { "get": { "operationId": "getLitigation", "summary": "Court Litigation History", "description": "Returns court cases involving an NZX company or its directors from the High Court, Court of Appeal, and Supreme Court. Includes case type, citation, dates, party role, and damages.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Court Litigation History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-history/{slug}": { "get": { "operationId": "getDirectorHistory", "summary": "Director Company History", "description": "Returns a director\\", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Director Company History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-network": { "get": { "operationId": "listDirectorNetwork", "summary": "Director Network Analysis", "description": "Cross-directorship and board interlock analysis with 3 modes: (1) company mode (?ticker=AIR) — shows all directors\\", "tags": [ "Directors" ], "x-tier": "free", "responses": { "200": { "description": "Director Network Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-workload/{slug}": { "get": { "operationId": "getDirectorWorkload", "summary": "Director Workload Analysis", "description": "Workload analysis for a director — current NZX board seats, active Companies Office directorships, overboarding risk level, board meeting attendance rate, tenure at each board, and chair/committee roles.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Director Workload Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-pipeline": { "get": { "operationId": "listBoardPipeline", "summary": "Board Pipeline", "description": "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 recruitment.", "tags": [ "Directors" ], "x-tier": "free", "responses": { "200": { "description": "Board Pipeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/company-failures/{slug}": { "get": { "operationId": "getCompanyFailure", "summary": "Company Failure Analysis", "description": "A director\\", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company Failure Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/select-committee/{ticker}": { "get": { "operationId": "getSelectCommittee", "summary": "Select Committee Activity", "description": "Returns NZ Parliament select committee reports and corporate submissions involving an NZX company. Covers financial scrutiny, bill reviews, SOE annual reviews, inquiries, and corporate submissions to select committees.", "tags": [ "Public Sector" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Select Committee Activity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/councillor-interests/{council-slug}": { "get": { "operationId": "getCouncillorInterest", "summary": "Councillor Pecuniary Interests", "description": "Get declared pecuniary interests for elected councillors on a specific NZ council. Returns interests grouped by councillor with category breakdown, person metadata, and optional entity/summary enrichment. Data from council interest registers under the Local Authorities (Members\\", "tags": [ "Public Sector" ], "x-tier": "free", "parameters": [ { "name": "council-slug", "in": "path", "required": true, "description": "Path parameter: council-slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Councillor Pecuniary Interests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/watchlist": { "get": { "operationId": "listWatchlist", "summary": "Watchlist Management", "description": "Manage your company watchlists. GET lists all watchlists for the authenticated user. POST creates a new watchlist with up to 50 tickers.", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "Watchlist Management", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/keyword-alerts": { "get": { "operationId": "listKeywordAlerts", "summary": "Keyword Alerts", "description": "Manage keyword alerts that scan NZX announcements. GET lists alerts with optional match history. POST creates a new alert with up to 20 keywords.", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "Keyword Alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/company-pager/{ticker}": { "get": { "operationId": "getCompanyPager", "summary": "Company One-Pager", "description": "Auto-generated company snapshot with key financial metrics, governance score, dividends, insider activity, risk flags, and recent announcements. Also available as a branded PDF at /api/v1/company-pager/{ticker}/pdf (supports white-label branding via ?branding=partner&logo_url=...&org_name=...).", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company One-Pager", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/morning-brief": { "get": { "operationId": "listMorningBrief", "summary": "Morning Brief", "description": "Your daily intelligence digest for watched companies. Returns overnight announcements, insider trades, price moves, dividends, and governance changes. Use ?generate=true to generate today\\", "tags": [ "Alerts" ], "x-tier": "free", "responses": { "200": { "description": "Morning Brief", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/backtest": { "post": { "operationId": "runBacktest", "summary": "Strategy Backtester", "description": "Backtest any screener filter combination against historical NZX data. 6 weighting methods: equal, market-cap, inverse market-cap, Mean-Variance Optimization (MVO), Black-Litterman (broker consensus views), Hierarchical Risk Parity (HRP). Annual rebalancing using financial_metrics + stock_prices. Returns equity curve, period-by-period holdings, risk-adjusted statistics (Sharpe, Sortino, max drawdown), and portfolio optimization results (efficient frontier, optimal weights). Supports price or total return (dividend-adjusted). Benchmark: FNZ ETF (Smartshares NZ Top 50). 7 statistically validated factors (|t|>2.0): P/B ratio, earnings yield, net profit growth, net debt/EBITDA, EV/EBITDA, P/E ratio, net margin.", "tags": [ "Analytics" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object" }, "description": "Array of {metric, operator, value} filters (same format as screener presets)" }, "startYear": { "type": "integer", "description": "Backtest start year (default: current year - 5, min: 2016)" }, "endYear": { "type": "integer", "description": "Backtest end year (default: current year)" }, "adjustForAnnouncement": { "type": "string", "enum": [ "true", "false" ], "description": "Delay rebalancing to actual annual results announcement dates, eliminating look-ahead bias (default: false)" } }, "required": [ "filters" ] } } } }, "responses": { "200": { "description": "Strategy Backtester", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/macro/regime": { "get": { "operationId": "getMacroRegime", "summary": "Macro Regime", "description": "Current NZ macroeconomic regime snapshot: OCR rate, GDP growth, CPI inflation, unemployment, NZD/USD, and economic cycle classification (expansion, slowdown, contraction, recovery). Updated weekly after RBNZ decisions and quarterly for Stats NZ releases.", "tags": [ "Macro" ], "x-tier": "free", "responses": { "200": { "description": "Macro Regime", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/macro/ocr-history": { "get": { "operationId": "getMacroOcrHistory", "summary": "OCR History", "description": "Complete RBNZ Official Cash Rate decision history (1999-present). 84 decisions with rate, change in basis points, decision type (cut/hike/hold), and governor name.", "tags": [ "Macro" ], "x-tier": "free", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by decision type: cut, hike, hold", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OCR History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/macro-exposure/{ticker}": { "get": { "operationId": "getMacroExposure", "summary": "Company Macro Exposure", "description": "Per-company macroeconomic exposure scoring: OCR sensitivity, FX sensitivity, economic cyclicality, overall macro risk score, and key exposure text. Based on sector classification and financial leverage metrics.", "tags": [ "Macro" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., AIR, FPH, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company Macro Exposure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/macro/indicators": { "get": { "operationId": "getMacroIndicators", "summary": "Macro Indicators", "description": "Historical NZ macroeconomic indicators: GDP growth, CPI inflation, unemployment rate. Quarterly data from Stats NZ with FRED fallback.", "tags": [ "Macro" ], "x-tier": "free", "parameters": [ { "name": "indicator", "in": "query", "required": false, "description": "Filter: gdp, cpi, unemployment", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max records (default: 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Macro Indicators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/property-portfolio/{ticker}": { "get": { "operationId": "getPropertyPortfolio", "summary": "Property Portfolio", "description": "Property portfolio data for NZX-listed REITs and property companies. Returns individual properties with addresses, book values ($000s), cap rates, WALE, occupancy, major tenants, geocoded lat/lng, climate risk scoring (composite score 0-100, seismic zone, flood/liquefaction/sea level rise risk), plus summary stats, type/regional breakdowns, top tenants, and development pipeline. Covers ~10 property companies (KPG, ARG, PFI, VHP, IPL, SPG, CDI, GMT, PCT, APL).", "tags": [ "Property" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., KPG, GMT, PFI, ARG)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Property Portfolio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/corporate-relationships/{ticker}": { "get": { "operationId": "getCorporateRelationship", "summary": "Corporate Relationships", "description": "Professional service relationships for an NZX company — auditors (with tenure years and fee breakdown), law firms/solicitors, share registrars, and bankers. Includes shared adviser detection (other NZX companies using the same professional firms) and relationship summary.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Corporate Relationships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/corporate-giving/{ticker}": { "get": { "operationId": "getCorporateGiving", "summary": "Corporate Giving", "description": "Corporate donations, sponsorships, and community investment for an NZX company. Cross-linked to registered charities where possible. Returns recipients, amounts, donation types (cash/sponsorship/community_investment/grant/in-kind), and foundation details.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., CEN, MEL, FPH)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Corporate Giving", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/professional-firms/{slug}": { "get": { "operationId": "getProfessionalFirm", "summary": "Professional Firm Profile", "description": "Detailed professional services firm profile with full client list. Covers law firms/solicitors, auditors, share registrars, and bankers. Returns firm metadata, current and historical NZX client relationships, and summary statistics.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Firm URL slug (e.g., chapman-tripp, kpmg, computershare)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Professional Firm Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/board-search": { "get": { "operationId": "listBoardSearch", "summary": "Board Search Engine", "description": "Search 2,000+ NZX directors matching board vacancy criteria. Multi-filter matching across skills, sector experience, governance track record, and availability. Returns ranked candidates with 5-dimension match scores.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "skills", "in": "query", "required": false, "description": "Comma-separated skill categories (financial, strategy, technology, governance, risk_management, legal_compliance, hr_remuneration, sustainability, international, industry_knowledge, stakeholder_relations, digital)", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector experience", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "Gender filter (male/female)", "schema": { "type": "string" } }, { "name": "max_boards", "in": "query", "required": false, "description": "Maximum current board seats", "schema": { "type": "integer" } }, { "name": "available_only", "in": "query", "required": false, "description": "Only directors with ≤2 current boards", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "exclude_ticker", "in": "query", "required": false, "description": "Exclude directors on this company (conflict avoidance)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 20, max 100)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Board Search Engine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/first-time-chairs": { "get": { "operationId": "listFirstTimeChairs", "summary": "First-Time Chairs", "description": "Get NZX directors serving as board chair for the first time. Useful for governance transition analysis and succession planning.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "recent_only", "in": "query", "required": false, "description": "Only chairs appointed in the last 2 years", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 50, max 200)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "First-Time Chairs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/chart-data/{ticker}": { "get": { "operationId": "getChartData", "summary": "Interactive Chart Data", "description": "Combined price, fundamental, and macro chart data for interactive overlays. Returns daily OHLCV prices, annual/interim financial metrics (EBITDA, revenue, net profit), earnings results, and RBNZ OCR decisions — all aligned by date for TradingView Lightweight Charts rendering.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD), default 5 years ago", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD), default today", "schema": { "type": "string" } }, { "name": "series", "in": "query", "required": false, "description": "Comma-separated series to include: price, fundamentals, macro (default: all)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interactive Chart Data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/earnings-calendar": { "get": { "operationId": "listEarningsCalendar", "summary": "Earnings Calendar", "description": "Predicted HY and FY reporting dates for all NZX companies, based on historical announcement patterns. Filter by ticker, sector, or date range.", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Filter by NZX ticker symbol", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "required": false, "description": "Filter by sector", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Earnings Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/economic-calendar": { "get": { "operationId": "listEconomicCalendar", "summary": "Economic Calendar", "description": "NZ macroeconomic event calendar covering RBNZ OCR decisions, GDP releases, CPI data, and employment reports. Filter by event type and date range.", "tags": [ "Macro" ], "x-tier": "free", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Event type: ocr, gdp, cpi, employment (comma-separated)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Economic Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/snowflake/{ticker}": { "get": { "operationId": "getSnowflake", "summary": "Portfolio Snowflake", "description": "5-axis radar chart scores for visual company assessment. Returns Value, Growth, Health, Governance, and Dividends axis scores (0-100) with the underlying metrics driving each score.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portfolio Snowflake", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/investment-checks/{ticker}": { "get": { "operationId": "getInvestmentCheck", "summary": "Investment Checks", "description": "16 pass/fail fundamental checks for quick due diligence. Each check returns a pass/fail result with the actual value and threshold used.", "tags": [ "Analytics" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investment Checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/news-sentiment/{ticker}": { "get": { "operationId": "getNewsSentiment", "summary": "News Sentiment", "description": "News articles and sentiment for a company. Aggregates and scores sentiment from NZ financial news RSS feeds (Interest.co.nz, NZ Herald, RNZ, NBR, Stuff) with per-article sentiment and rolling averages.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback period in days (default: 30)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "News Sentiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/insider-correlation/{ticker}": { "get": { "operationId": "getInsiderCorrelation", "summary": "Insider-Announcement Correlation", "description": "Insider trade and announcement tone correlation patterns for a company. Cross-references insider trading activity with announcement sentiment to surface patterns where insiders trade ahead of tone shifts.", "tags": [ "Insider Trades" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } }, { "name": "months", "in": "query", "required": false, "description": "Lookback period in months (default: 12)", "schema": { "type": "integer" } }, { "name": "window_days", "in": "query", "required": false, "description": "Window in days around announcements to check for insider trades (default: 30)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Insider-Announcement Correlation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/network-intelligence": { "get": { "operationId": "listNetworkIntelligence", "summary": "Network Intelligence", "description": "Director network analysis powered by Graphology. Find shortest connection paths between people, identify power brokers by centrality scoring, detect governance communities via Louvain clustering. Cross-platform: NZX + charity + public sector + iwi connections.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Person slug for shortest-path source", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Person slug for shortest-path target", "schema": { "type": "string" } }, { "name": "current_only", "in": "query", "required": false, "description": "true/false (default: true)", "schema": { "type": "string" } }, { "name": "cross_platform", "in": "query", "required": false, "description": "Include charity/public sector (default: true)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 30)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Network Intelligence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/remuneration-benchmarks": { "get": { "operationId": "listRemunerationBenchmarks", "summary": "Remuneration Benchmarks", "description": "Director compensation benchmarks with P25/median/P75 percentiles. Filter by role (chair/NED), sector, market cap quartile, board size. Includes 5-year trend and sector/role breakdowns. Supersedes IoD annual Directors\\", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Specific financial year", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Remuneration Benchmarks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/skill-search": { "get": { "operationId": "listSkillSearch", "summary": "Skills Taxonomy Search", "description": "Search the ESCO-aligned skills taxonomy (12 categories, 68 sub-skills, 350+ NZ-specific synonyms) for fuzzy skill matching. Maps free-text queries like ", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 20)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Skills Taxonomy Search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/insolvency/{slug}": { "get": { "operationId": "getInsolvency", "summary": "Insolvency Screening", "description": "Check insolvency/bankruptcy history for any person. Returns MBIE Insolvency Register records filtered by cl 4.5-4.6 TTL rules (4yr bankruptcy, 5yr summary instalment). Shows adjudication dates, discharge status, match confidence, and TTL exemption status.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Insolvency Screening", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/directorships/{slug}": { "get": { "operationId": "getDirectorship", "summary": "Full Directorship Network", "description": "Full company directorship history from the NZ Companies Register. Shows NZX board positions plus private company roles, current and historical, with company status and failure rate analysis. Richer than director-history endpoint which uses director slug — this uses person slug and covers the complete Companies Office record.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Path parameter: slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full Directorship Network", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fair-value/{ticker}": { "get": { "operationId": "getFairValue", "summary": "Fair Value Estimate", "description": "Multi-model fair value estimation using DCF (discounted cash flow), Dividend Discount Model (Gordon Growth), and EV/EBITDA relative valuation. Returns composite estimate, individual model outputs, confidence level, and methodology notes. Assumptions are user-adjustable via query parameters. This is an automated estimate, not a target price or investment recommendation.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "discount_rate", "in": "query", "required": false, "description": "Discount rate / WACC (default: 0.10 = 10%)", "schema": { "type": "number" } }, { "name": "terminal_growth", "in": "query", "required": false, "description": "Terminal growth rate (default: 0.025 = 2.5%)", "schema": { "type": "number" } }, { "name": "projection_years", "in": "query", "required": false, "description": "DCF projection years (default: 5)", "schema": { "type": "number" } }, { "name": "required_return", "in": "query", "required": false, "description": "Required return for DDM (default: 0.10 = 10%)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Fair Value Estimate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/earnings-presentations/{ticker}": { "get": { "operationId": "getEarningsPresentation", "summary": "Earnings Presentations", "description": "Earnings presentations and results commentary library. Returns AI-extracted tone, topics, summary, and speakers from NZX company results presentations. 357 presentations across 83 issuers (2017-2026).", "tags": [ "Earnings" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter by period type: annual, interim", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Filter by financial year", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Include additional data: transcript (full extracted text)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Earnings Presentations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/transcript-search": { "get": { "operationId": "listTranscriptSearch", "summary": "Earnings Transcript Search", "description": "Full-text search across 357 earnings call transcripts from NZX-listed companies. Returns matching snippets with highlighted search terms. Multi-word queries require ALL words present.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (multi-word supported, all words must match)", "schema": { "type": "string" } }, { "name": "ticker", "in": "query", "required": false, "description": "Filter by NZX ticker symbol", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Filter by financial year", "schema": { "type": "number" } }, { "name": "period", "in": "query", "required": false, "description": "Filter by period type: annual, interim", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default 20, max 50)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Earnings Transcript Search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/factor-grades/{ticker}": { "get": { "operationId": "getFactorGrade", "summary": "Factor Grades", "description": "A-F factor grades across 6 investment dimensions: Value, Growth, Profitability, Momentum, Dividends, and Governance. Each factor includes sub-metrics with percentile rankings against the NZX universe.", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g., FPH, AIR, SPK)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factor Grades", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stories": { "get": { "operationId": "listStories", "summary": "Stories (Media)", "description": "Media story leads from cross-signal analysis. Surfaces newsworthy data anomalies across 6 detection rule groups: signal fusion, overboarded directors, earnings surprises, large insider trades, political conflicts, and pay for failure. Requires media_access flag on user profile.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Lookback period in days (default: 90)", "schema": { "type": "number" } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category (e.g., governance, insider, earnings)", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "Filter by severity: breaking, significant, notable, background", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stories (Media)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/charities": { "get": { "operationId": "listCharities", "summary": "List Charities", "description": "Browse 44,000+ registered NZ charities with cursor-based pagination. Filter by sector, grade, region, revenue range, and active status. Uses parseCursorPagination() + buildCursorMeta() helpers for efficient traversal of large datasets.", "tags": [ "Charities" ], "x-tier": "free", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search by charity name", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active status (default: true)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "min_revenue", "in": "query", "required": false, "description": "Minimum total revenue in NZD", "schema": { "type": "number" } }, { "name": "max_revenue", "in": "query", "required": false, "description": "Maximum total revenue in NZD", "schema": { "type": "number" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor for next page (from meta.next_cursor)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor for previous page (from meta.prev_cursor)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 100 (default: 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Charities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/charities/{slug}": { "get": { "operationId": "getCharity", "summary": "Charity Detail", "description": "Full detail for a single registered NZ charity by slug. Optionally include officers, financials, and executives via the include parameter.", "tags": [ "Charities" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Charity slug (path parameter)", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated includes: officers, financials, executives", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Charity Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/charity-officers": { "get": { "operationId": "listCharityOfficers", "summary": "List Charity Officers", "description": "Browse 242,000+ charity officers (trustees, board members, secretaries) with cursor-based pagination. Uses parseCursorPagination() + buildCursorMeta() helpers for efficient traversal.", "tags": [ "Charities" ], "x-tier": "free", "parameters": [ { "name": "charity_id", "in": "query", "required": false, "description": "Filter by charity ID", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Search by officer name", "schema": { "type": "string" } }, { "name": "is_current", "in": "query", "required": false, "description": "Filter by current status", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "after", "in": "query", "required": false, "description": "Cursor for next page (from meta.next_cursor)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor for previous page (from meta.prev_cursor)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, max 100 (default: 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Charity Officers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/charity-briefing/{slug}": { "get": { "operationId": "getCharityBriefing", "summary": "Charity Board Briefing", "description": "Executive-ready charity due diligence report. Aggregates 7+ data sources into a 12-section briefing: metadata, ratings, financial health (3-year CAGR, government dependency), governance (trustee tenure, cross-platform links), executive compensation, officer changes (12-month), funding sources (concentration risk), service providers, peer snapshot, impact metrics, cross-platform connections, and key risks. Designed for grant committees, philanthropic advisors, and governance consultants. White-label support via query parameters.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Charity slug (path parameter)", "schema": { "type": "string" } }, { "name": "logo_url", "in": "query", "required": false, "description": "Custom logo URL for white-label reports", "schema": { "type": "string" } }, { "name": "org_name", "in": "query", "required": false, "description": "Custom organization name for white-label reports", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Charity Board Briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/charity-briefing/{slug}/pdf": { "get": { "operationId": "getCharityBriefingPdf", "summary": "Charity Board Briefing (Print)", "description": "Print-friendly HTML version of the charity board briefing. Open in a browser and use Save as PDF for a professional A4 document. Emerald/green charity branding with white-label support.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Charity slug (path parameter)", "schema": { "type": "string" } }, { "name": "logo_url", "in": "query", "required": false, "description": "Custom logo URL", "schema": { "type": "string" } }, { "name": "org_name", "in": "query", "required": false, "description": "Custom organization name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Charity Board Briefing (Print)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/thesis/{ticker}": { "get": { "operationId": "getThesi", "summary": "Thesis Invalidation Check", "description": "Check whether a bullish, bearish, or neutral investment thesis for an NZX company is being invalidated. Returns a composite invalidation score (0-100) across 4 signals: analyst consensus divergence, fair value gap, management credibility, and insider activity alignment.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR)", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Thesis direction: bullish, bearish, or neutral (default: bullish)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thesis Invalidation Check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/company-changes/{ticker}": { "get": { "operationId": "getCompanyChange", "summary": "Company Material Changes", "description": "Detect material changes for an NZX company by comparing consecutive announcement extractions. Surfaces revenue, NPAT, EBITDA, EPS, and net debt changes that exceed significance thresholds. Also includes recent board changes and dividend changes.", "tags": [ "Companies" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR)", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Lookback period in days (default: 30)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Company Material Changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/liquidity/{ticker}": { "get": { "operationId": "getLiquidity", "summary": "Liquidity Score", "description": "Kyle\\", "tags": [ "Market Data" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liquidity Score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ir-rehearsal/{ticker}": { "post": { "operationId": "runIrRehearsal", "summary": "IR Rehearsal Mode", "description": "Analyse a draft NZX announcement before publication. Scans for FMA compliance risks, defamation language, superlatives, negative market trigger words, forward-looking statements, hedging, and buried risks. Predicts sentiment, estimates media pickup probability, generates likely analyst questions, and detects corporate buzzwords.", "tags": [ "Research" ], "x-tier": "pro", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "IR Rehearsal Mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/narrative-risk/{ticker}": { "post": { "operationId": "runNarrativeRisk", "summary": "Narrative Risk Engine", "description": "Simulate multi-stakeholder reactions to a draft announcement. Analyses 5 stakeholder types (institutional, retail, media, analyst, regulator) and returns risk scoring, stakeholder reaction cards, signal conflicts, AI-recommended actions, and a Day 1/Week 1/Month 1 reaction timeline.", "tags": [ "Governance" ], "x-tier": "pro", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Narrative Risk Engine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agm-predictor/{ticker}": { "get": { "operationId": "getAgmPredictor", "summary": "AGM Voting Outcome Predictor", "description": "Predict AGM resolution outcomes using a 4-factor weighted model: historical category base rates (30%), company voting history (25%), fund manager alignment (25%), and governance context (20%). Uses 1,941 historical NZX resolutions and fund manager voting records.", "tags": [ "Proxy Advisory" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AGM Voting Outcome Predictor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/director-demographics/{ticker}": { "get": { "operationId": "getDirectorDemographic", "summary": "Board Demographics", "description": "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 1,017 director biographies.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Path parameter: ticker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board Demographics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/filing-diff": { "get": { "operationId": "listFilingDiff", "summary": "Filing Diff", "description": "Compare two NZX announcements side-by-side. Returns section-level diffs with line-level hunks showing additions, removals, and changes. Sections are auto-detected from ~40 common NZ annual report patterns (Risk Factors, Accounting Policies, Governance, Related-Party Disclosures, etc.). Supports LLM format for Copilot integration.", "tags": [ "Market Intelligence" ], "x-tier": "free", "parameters": [ { "name": "id1", "in": "query", "required": true, "description": "First announcement ID", "schema": { "type": "string" } }, { "name": "id2", "in": "query", "required": true, "description": "Second announcement ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filing Diff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/iwi-briefing/{id}": { "get": { "operationId": "getIwiBriefing", "summary": "Iwi Board Briefing", "description": "Executive-ready iwi/PSGE governance briefing. Aggregates 13+ data sources into a 12-section report: iwi profile, financial health (CAGR, self-sufficiency ratio, audit opinion), governance (skills coverage/gaps, tenure, risk flags), remuneration (fee trends, meeting attendance), commercial portfolio (subsidiaries, NZX holdings), assets (fisheries, forestry, property), distributions, strategic priorities, risks, sustainability, cross-platform connections, and peer snapshot. White-label support via query parameters.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Iwi ID (path parameter)", "schema": { "type": "string" } }, { "name": "logo_url", "in": "query", "required": false, "description": "Custom logo URL for white-label reports", "schema": { "type": "string" } }, { "name": "org_name", "in": "query", "required": false, "description": "Custom organization name for white-label reports", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Iwi Board Briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/iwi-briefing/{id}/pdf": { "get": { "operationId": "getIwiBriefingPdf", "summary": "Iwi Board Briefing (Print)", "description": "Print-friendly HTML version of the iwi board briefing. Open in browser and Save as PDF for a professional A4 document. Red/rose iwi branding with white-label support.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Iwi ID (path parameter)", "schema": { "type": "string" } }, { "name": "branding", "in": "query", "required": false, "description": "White-label branding mode", "schema": { "type": "string" } }, { "name": "logo_url", "in": "query", "required": false, "description": "Custom logo URL", "schema": { "type": "string" } }, { "name": "org_name", "in": "query", "required": false, "description": "Custom organization name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Iwi Board Briefing (Print)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/iwi-research/{id}": { "post": { "operationId": "createIwiResearch", "summary": "Iwi Deep Research (Streaming)", "description": "AI-powered deep research pipeline for iwi/PSGE entities. 5-phase Sonnet analysis: deterministic data fetch (17 sources), financial health, governance, commercial performance, community impact, then synthesis with source citations. Returns SSE stream of progress events. Pro+ tier required.", "tags": [ "Research" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Iwi ID (path parameter)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "description": "Optional research question to focus the analysis" } } } } } }, "responses": { "200": { "description": "Iwi Deep Research (Streaming)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/portfolio": { "get": { "operationId": "listPortfolio", "summary": "Get Portfolio", "description": "Returns the authenticated user\\", "tags": [ "Widgets" ], "x-tier": "free", "responses": { "200": { "description": "Get Portfolio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createPortfolio", "summary": "Add/Sync Holdings", "description": "Add a single holding or bulk sync all holdings. Single: send {ticker, shares_held?, avg_cost_nzd?, weight?}. Bulk: send {holdings: [...]} to replace all holdings. Max 100 holdings.", "tags": [ "Widgets" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "NZX ticker (for single add)" }, "shares_held": { "type": "number", "description": "Number of shares held" }, "avg_cost_nzd": { "type": "number", "description": "Average cost per share in NZD" }, "weight": { "type": "number", "description": "Target allocation weight (0-100)" }, "holdings": { "type": "string", "description": "Array of holdings for bulk sync" } } } } } }, "responses": { "200": { "description": "Add/Sync Holdings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/portfolio/enriched": { "get": { "operationId": "getPortfolioEnriched", "summary": "Enriched Portfolio", "description": "Returns the user\\", "tags": [ "Widgets" ], "x-tier": "free", "responses": { "200": { "description": "Enriched Portfolio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/supplier-governance/{id}": { "get": { "operationId": "getSupplierGovernance", "summary": "Supplier Governance Intelligence", "description": "Director intelligence for a government contract supplier. Returns directors from Companies Office NZBN API, cross-referenced against shared.people to identify MPs, NZX directors, charity trustees, iwi officers, and public sector appointees who also serve as government supplier directors. Enables conflict-of-interest detection and revolving door analysis.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID from shared.companies (path parameter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supplier Governance Intelligence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/committee-chairs": { "get": { "operationId": "listCommitteeChairs", "summary": "Board Committee Memberships", "description": "Board committee membership data across NZX companies. Returns committee chairs, composition breakdown, and filtering by committee type, ticker, or sector. Data sourced from director_committee_memberships table.", "tags": [ "Directors" ], "x-tier": "free", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results returned (default: 50, max: 200)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Board Committee Memberships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/alpha-score/{ticker}": { "get": { "operationId": "getAlphaScore", "summary": "Composite Alpha Score", "description": "Composite 0-100 alpha score combining 5 proprietary signal dimensions (governance, insider conviction, management credibility, financial quality, dividend sustainability) validated on 10 years of NZX data. Returns component breakdown, active signal flags with alpha spreads, validated factor match bonus, and rating scale methodology.", "tags": [ "Analytics" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Composite Alpha Score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/remuneration-compliance/{ticker}": { "get": { "operationId": "getRemunerationCompliance", "summary": "Remuneration Disclosure Compliance", "description": "Score an NZX company against 8 NZX Corporate Governance Code v1.7 remuneration disclosure criteria. Returns 0-100 score with A-F grade, per-criterion breakdown with evidence.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remuneration Disclosure Compliance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/disclosure-language/{ticker}": { "get": { "operationId": "getDisclosureLanguage", "summary": "Disclosure Language Analysis", "description": "Analyze disclosure style evolution for an NZX company. Tracks 5 NLP dimensions: hedging trajectory, sentiment volatility, buried risk frequency, guidance consistency, and forward-looking density.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disclosure Language Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agm-notice/{ticker}": { "get": { "operationId": "getAgmNotice", "summary": "AGM Notice Draft", "description": "Auto-draft Notice of Annual Meeting from existing data. 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.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AGM Notice Draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/greenwashing/{ticker}": { "get": { "operationId": "getEsgDisclosureGap", "summary": "ESG Disclosure Gap Analysis", "description": "Compare ESG claims against measured outcomes. Analyzes narrative score (sustainability language in announcements) vs evidence score (actual emissions, diversity, safety data). Identifies potential gaps between ESG narrative and measured outcomes.", "tags": [ "Governance" ], "x-tier": "free", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ESG Narrative-Data Alignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "$ref": "#/components/headers/RateLimitHeaders" } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ask": { "post": { "operationId": "askCopilot", "summary": "Ask NZXplorer Copilot", "description": "Natural language query interface backed by Claude Sonnet with tool-calling against 100+ internal API endpoints. Returns SSE streaming response. Supports personas, session memory, and structured card responses.", "tags": [ "Copilot" ], "x-tier": "free", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "description": "Natural language query about NZX data" }, "message": { "type": "string", "description": "Alias for question" }, "persona": { "type": "string", "description": "Persona ID (e.g. macro, governance, risk, buffett, fund_manager)" }, "session_id": { "type": "string", "description": "Session UUID for conversation continuity" }, "conversation": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } }, "description": "Previous conversation turns for context" } }, "required": [ "question" ] } } } }, "responses": { "200": { "description": "SSE streaming response", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "API health check", "description": "Returns pass/fail status for each core data table. No authentication required.", "tags": [ "System" ], "x-tier": "free", "security": [], "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "down" ] }, "checks": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "pass", "fail" ] } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key passed via the X-API-Key header" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "API key passed as a query parameter" } }, "parameters": { "ticker": { "name": "ticker", "in": "path", "required": true, "description": "NZX ticker symbol (e.g. FPH, AIR, MEL)", "schema": { "type": "string", "example": "FPH" } }, "slug": { "name": "slug", "in": "path", "required": true, "description": "URL-friendly slug identifier", "schema": { "type": "string", "example": "lewis-gradon" } }, "search": { "name": "search", "in": "query", "description": "Search by name (partial match)", "schema": { "type": "string" } }, "sector": { "name": "sector", "in": "query", "description": "Filter by NZX sector", "schema": { "type": "string", "example": "Healthcare" } }, "year": { "name": "year", "in": "query", "description": "Year filter. Single year (2024) or range (2020-2024)", "schema": { "type": "string", "example": "2024" } }, "limit": { "name": "limit", "in": "query", "description": "Number of results to return (1-500)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, "offset": { "name": "offset", "in": "query", "description": "Number of results to skip for pagination", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "order": { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, "format": { "name": "format", "in": "query", "description": "Response format. `llm` returns token-optimized output (~70% fewer tokens). `fdc3` returns FINOS FDC3 v2.0 context objects. `toon` returns ultra-compact pipe-delimited tabular format.", "schema": { "type": "string", "enum": [ "standard", "llm", "fdc3", "toon" ] } } }, "headers": { "RateLimitHeaders": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit window resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Maximum requests allowed per day", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining for today", "schema": { "type": "integer" } }, "X-API-Tier": { "description": "Authenticated API key tier (free, pro, enterprise, institutional)", "schema": { "type": "string" } }, "X-Request-ID": { "description": "Unique request ID (UUID v4) for support correlation", "schema": { "type": "string", "format": "uuid" } } } }, "schemas": { "Envelope": { "type": "object", "description": "Standard API response envelope", "properties": { "data": { "description": "Response payload" }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v1" }, "timestamp": { "type": "string", "format": "date-time" }, "format": { "type": "string", "enum": [ "standard", "llm", "fdc3", "toon" ] }, "endpoint": { "type": "string" } } } } }, "PaginatedEnvelope": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching records" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string" } } } } } ] }, "CompanySummary": { "type": "object", "properties": { "id": { "type": "integer" }, "ticker": { "type": "string", "example": "FPH" }, "name": { "type": "string", "example": "Fisher & Paykel Healthcare Corporation Limited" }, "sector": { "type": "string", "example": "Healthcare" }, "slug": { "type": "string" }, "market_cap": { "type": "number", "description": "Market capitalisation in NZD (whole dollars)", "nullable": true }, "website_url": { "type": "string", "format": "uri", "nullable": true }, "isin": { "type": "string", "example": "NZFAPE0001S2", "nullable": true }, "lei": { "type": "string", "nullable": true }, "exchange_mic": { "type": "string", "example": "XNZE", "nullable": true } } }, "DirectorSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string", "example": "Lewis Gradon" }, "slug": { "type": "string", "example": "lewis-gradon" }, "short_bio": { "type": "string", "nullable": true } } }, "Dividend": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "example": 2025 }, "period_type": { "type": "string", "enum": [ "final", "interim", "special" ] }, "announcement_date": { "type": "string", "format": "date", "nullable": true }, "ex_date": { "type": "string", "format": "date", "nullable": true }, "record_date": { "type": "string", "format": "date", "nullable": true }, "payment_date": { "type": "string", "format": "date", "nullable": true }, "dps_cents": { "type": "number", "description": "Dividends per share in cents", "nullable": true }, "total_paid": { "type": "number", "description": "Total dividends paid in NZD thousands", "nullable": true }, "imputation_percent": { "type": "number", "description": "Imputation credit percentage (0-100)", "nullable": true }, "supplementary_dps_cents": { "type": "number", "nullable": true }, "currency": { "type": "string", "example": "NZD", "nullable": true }, "drp_available": { "type": "boolean", "nullable": true }, "source": { "type": "string", "nullable": true } } }, "DividendSummary": { "type": "object", "properties": { "latest_dps_cents": { "type": "number", "nullable": true }, "dividend_yield": { "type": "number", "description": "Trailing dividend yield (%)", "nullable": true }, "payout_ratio": { "type": "number", "description": "Payout ratio (%)", "nullable": true }, "dividend_cover": { "type": "number", "description": "Dividend cover (x)", "nullable": true }, "total_records": { "type": "integer" } } }, "EarningsResult": { "type": "object", "properties": { "fiscal_year": { "type": "integer" }, "period_type": { "type": "string", "enum": [ "annual", "interim" ] }, "revenue": { "type": "number", "description": "Revenue in NZD thousands", "nullable": true }, "net_profit": { "type": "number", "description": "Net profit in NZD thousands", "nullable": true }, "ebitda": { "type": "number", "nullable": true }, "ebit": { "type": "number", "nullable": true }, "underlying_profit": { "type": "number", "nullable": true }, "eps_cents": { "type": "number", "description": "Earnings per share in cents", "nullable": true }, "dividends_per_share_cents": { "type": "number", "nullable": true }, "guidance_text": { "type": "string", "nullable": true }, "guidance_direction": { "type": "string", "enum": [ "up", "down", "maintained", "withdrawn", "new" ], "nullable": true } } }, "AlertSubscriptionCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "Subscription name" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "insider_trade", "capital_raise", "dividend", "earnings", "agm_result", "director_change", "grs_change", "technical_signal", "credit_rating", "audit_change", "takeover" ] } }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific tickers (empty = all)" }, "sectors": { "type": "array", "items": { "type": "string" } }, "severity_levels": { "type": "array", "items": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] } }, "anomaly_categories": { "type": "array", "items": { "type": "string", "enum": [ "insider", "governance", "financial", "market", "agm", "corporate" ] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 signing secret" }, "is_active": { "type": "boolean", "default": true } }, "required": [ "name", "webhook_url", "signal_types" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "message": { "type": "string", "description": "Human-readable explanation", "nullable": true }, "docs": { "type": "string", "format": "uri", "description": "Link to API documentation", "nullable": true }, "retry_after_seconds": { "type": "integer", "description": "Seconds to wait before retrying (rate limit only)", "nullable": true } }, "required": [ "error" ] } }, "responses": { "BadRequest": { "description": "Bad request — invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing API key", "message": "Include your API key via X-API-Key header or ?api_key= query parameter.", "docs": "https://nzxplorer.co.nz/developers" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Rate limit exceeded", "message": "free tier allows 10 requests/minute.", "retry_after_seconds": 45 } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Always 0 when rate limited", "schema": { "type": "integer" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }