NZXplorer Market Intelligence API

Signals, anomalies, sentiment, semantic search, and risk language

GitHub OpenAPI

Operations 18

GET /announcements Announcements #
POST /signals/detect Signal Fusion Detection #
POST /announcements/{id}/extract Announcement PDF Reader #
GET /capital-raise-sentiment/{ticker} Capital Raise Sentiment #
GET /signals Market Intelligence Feed #
GET /anomalies Market Anomaly Detection #
GET /semantic-search Semantic Search #
GET /risk-language/{ticker} Risk Language Scores #
GET /keyword-trends Keyword Trend Analysis #
GET /announcement-alerts List Announcement Alert Rules #
POST /announcement-alerts Create Announcement Alert Rule #
PATCH /announcement-alerts/{id} Update Announcement Alert Rule #
DELETE /announcement-alerts/{id} Delete Announcement Alert Rule #
GET /announcement-alerts/{id}/matches List Announcement Alert Matches #
GET /zapier/triggers/announcements Zapier: New Announcement #
GET /sentiment/{ticker} Announcement Sentiment #
GET /news-sentiment/{ticker} News Sentiment #
GET /filing-diff Filing Diff #

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-market-intelligence-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-market-intelligence-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NZXplorer Market Intelligence 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: Market Intelligence
  description: Signals, anomalies, sentiment, semantic search, and risk language
paths:
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
  /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'
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