NZXplorer Directors API

Director profiles, board composition, skills, and due diligence

GitHub OpenAPI

Operations 23

GET /directors List Directors #
GET /directors/{slug} Director Detail #
GET /ir-dashboard/{ticker} IR Dashboard #
POST /alerts/board-events Board Event Webhooks #
GET /skills-matrix/{ticker} Board Skills Matrix #
GET /board-gap-report/{ticker} Board Gap Intelligence Report #
GET /board-gap-report/{ticker}/pdf Board Gap Report PDF #
GET /board-vacancies Board Vacancies #
GET /director-report/{slug} Director Due Diligence Report #
GET /board-changes/{ticker} Board Changes #
GET /board-report/{ticker} Board Composition Report #
GET /director-conflicts/{ticker} Director Conflicts #
GET /prohibited-directors Prohibited Directors #
GET /director-history/{slug} Director Company History #
GET /director-network Director Network Analysis #
GET /director-workload/{slug} Director Workload Analysis #
GET /board-pipeline Board Pipeline #
GET /company-failures/{slug} Company Failure Analysis #
GET /board-search Board Search Engine #
GET /first-time-chairs First-Time Chairs #
GET /directorships/{slug} Full Directorship Network #
GET /director-demographics/{ticker} Board Demographics #
GET /committee-chairs Board Committee Memberships #

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-directors-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-directors-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NZXplorer Directors 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: Directors
  description: Director profiles, board composition, skills, and due diligence
paths:
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
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