NZXplorer Governance API

Governance Risk Scores, compliance, political connections, KYC screening

GitHub OpenAPI

Operations 22

GET /governance Governance Scores #
GET /compliance-calendar/{ticker} Compliance Calendar #
GET /management-credibility/{ticker} Management Credibility #
GET /kyc-screening/{slug} KYC/AML Director Screening #
GET /zapier/triggers/grs-changes Zapier: GRS Score Change #
GET /board-effectiveness/{ticker} Board Effectiveness Dashboard #
GET /board-benchmark/{ticker} Board Evaluation Benchmarking #
GET /chair-ceo-alignment/{ticker} Chair vs CEO Communication Alignment #
GET /government-contracts/{ticker} Government Contracts #
GET /hidden-connections/{ticker} Hidden Connections #
GET /succession-plan/{ticker} Succession Plan #
GET /director-questionnaire/{ticker}/{slug} D&O Questionnaire Auto-Fill #
GET /interest-register/{ticker} Interest Register #
GET /regulatory-actions/{ticker} Regulatory Actions #
GET /political-connections/{ticker} Political Connections #
GET /litigation/{ticker} Court Litigation History #
POST /narrative-risk/{ticker} Narrative Risk Engine #
GET /supplier-governance/{id} Supplier Governance Intelligence #
GET /remuneration-compliance/{ticker} Remuneration Disclosure Compliance #
GET /disclosure-language/{ticker} Disclosure Language Analysis #
GET /agm-notice/{ticker} AGM Notice Draft #
GET /greenwashing/{ticker} ESG Disclosure Gap Analysis #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nzxplorer-co-nz:nzxplorer-co-nz-governance-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nzxplorer-co-nz-governance-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NZXplorer Governance 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.


    All 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: Governance
  description: Governance Risk Scores, compliance, political connections, KYC screening
paths:
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /remuneration-compliance/{ticker}:
    get:
      operationId: getRemunerationCompliance
      summary: Remuneration Disclosure Compliance
      description: Check an NZX company against 8 remuneration disclosure items drawn from the NZX Corporate Governance Code v1.7. Returns found, partly_found, not_found or not_applicable for each item, with what was searched. Four items are searched for in announcement titles only, not annual reports, so not_found does not mean the company fails to disclose. No score or grade.
      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'
components:
  responses:
    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'
    InternalError:
      description: Internal server error
      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
  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
    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
  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
  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