findadoctor-si Waitlist API

openapi: 3.2.0
info:
  title: FindADoctor.si New Zealand Waitlist API
  version: nz-2026-10-15.2
  description: Read-only JSON API with the same tools as the MCP server. No sign-up needed. Not medical advice; in an emergency call 111. Responses list the main fields (components.schemas); other fields may appear, so ignore fields you do not know. Fields without data are left out.
  x-llms-txt: https://api-nz.findadoctor.si/llms.txt
servers:
- url: https://api-nz.findadoctor.si
security:
- {}
- accountKey: []
tags:
- name: Waitlist
paths:
  /api/v1/waitlist:
    get:
      operationId: publicWaitlist
      summary: Health NZ public waiting lists by district and specialty
      description: 'Public-system waiting lists from Health NZ by district and specialty (latest month and the same month a year earlier): people waiting for a first specialist assessment (FSA) and for planned treatment (surgery), and the share waiting over 120 days. Use it when the person is weighing public against private, or which district is faster. Give specialty and/or district. Free.'
      parameters:
      - name: specialty
        in: query
        required: false
        description: e.g. 'Orthopaedic', 'ENT', 'General Surgery', 'eye'. An exact name is matched first, then names containing each word, then the same without words like 'surgery' and with common plain words mapped (eye → Ophthalmology, heart surgery → Cardiothoracic, cardiologist → Cardiology, internal medicine → General Medicine), then part of a name; both of Health NZ's names for the same specialty are returned (e.g. Orthopaedics and Orthopaedic Surgery).
        schema:
          type: string
          maxLength: 200
      - name: district
        in: query
        required: false
        description: Health NZ district, e.g. 'Auckland', 'Canterbury', 'Capital and Coast'. Part of a name also matches (Canterbury includes South Canterbury); a city or region is read as its district (Wellington → Capital and Coast, Dunedin → Southern), shown in district_read_as.
        schema:
          type: string
          maxLength: 200
      responses:
        '200':
          description: JSON result (same as the MCP tool's result)
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    $ref: '#/components/schemas/Provider'
                  rows:
                    type: array
                    items:
                      $ref: '#/components/schemas/WaitlistRow'
                  more:
                    type: boolean
                  explain:
                    type: string
                  district_read_as:
                    type: array
                    items:
                      type: string
                      description: district names searched when the district given was a city or region
                  source:
                    type: string
                  next_step:
                    type: string
                  specialties:
                    type: array
                    items:
                      type: string
                  districts:
                    type: array
                    items:
                      type: string
        '400':
          description: 'bad arguments, or the search was too broad (too_slow): the message says what to change'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'the Authorization header was sent but is invalid or expired (invalid_token): send no header or a valid account key'
          headers:
            WWW-Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate_limited (too many requests) or daily_limit (daily doctor limit reached); the message says when it resets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: seconds to wait
              schema:
                type: integer
        '500':
          description: internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'busy or starting (busy, unavailable): retry after Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: seconds to wait
              schema:
                type: integer
      tags:
      - Waitlist
components:
  schemas:
    Provider:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        data_version:
          type: string
      description: who publishes this data and which build
    WaitlistRow:
      type: object
      properties:
        measure:
          type: string
        month_end:
          type: string
        region:
          type: string
        district:
          type: string
        specialty:
          type: string
        total_waiting:
          type: integer
        waiting_under_120_days:
          type: integer
        share_over_120_days:
          type: number
        has_cells_under_5:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
          description: bad_args, too_slow, daily_limit, rate_limited, busy, unavailable, sign_in_required, invalid_token, cross_site, not_found, internal
        message:
          type: string
          description: what to change or when to retry
  securitySchemes:
    accountKey:
      type: http
      scheme: bearer
      description: Optional account key (dk_...); accounts are by invitation during the trial.