openapi: 3.2.0
info:
  title: AEMC Energy Rules Rule Versions API
  version: '2026-07-27'
  description: 'Machine-readable description of the undocumented JSON API that serves the Australian Energy Market Commission''s Energy Rules application at https://energy-rules.aemc.gov.au. It exposes the consolidated, versioned text of the National Electricity Rules (NER), National Gas Rules (NGR) and National Energy Retail Rules (NERR) — the rule versions and their PDF/DOCX artefacts, the table of contents, every chapter/part/division/rule/clause node, the full-text search index and the complete defined-terms glossary.


    AEMC publishes NO OpenAPI, no developer portal and no API documentation for this surface. This document is DERIVED, not harvested. Every path below is a literal route string taken from AEMC''s own shipped production JavaScript bundle (https://de4oj9etm9d7w.cloudfront.net/b8470902-3d28-4902-8883-2c59d10e7818/js/app.js), and each one was probed live and anonymously on 2026-07-27 with the observed HTTP status recorded in `x-evidence`. Response schemas are derived ONLY from responses actually observed on those probes — no field, parameter or status code is invented.


    ACCESS: entirely anonymous. No API key, no OAuth, no cookie and no CSRF token was required for any read endpoint probed; responses carry `x-ratelimit-limit: 1000` and `x-ratelimit-remaining`, served through AWS API Gateway (`apigw-requestid`) in front of a Laravel application (Laravel API Resource `data`/`links`/`meta` envelope, Laravel-style pagination).


    NOT MODELLED: the production bundle also contains an administrative, token-gated approval route of the form `/api/v1/{type}/{version}/approve/{token}` used by the editorial preview workflow. It is a state-changing endpoint, it was deliberately NOT probed, and it is deliberately not modelled here. The `previewToken` query parameter that several read endpoints accept belongs to the same editorial preview workflow and is not usable anonymously.


    STATUS: this is an undocumented internal API of a public website, not a product AEMC offers or supports. There is no published terms-of-use, rate-limit policy, SLA, versioning policy or contact for it. Treat it as subject to change without notice, and report inaccuracies rather than treating this document as an authoritative contract.'
  contact:
    name: AEMC
    url: https://www.aemc.gov.au/contact-us
  x-provenance:
    generated: '2026-07-27'
    method: derived
    sources:
    - https://de4oj9etm9d7w.cloudfront.net/b8470902-3d28-4902-8883-2c59d10e7818/js/app.js
    - live anonymous HTTP probes 2026-07-27
    note: Not published by AEMC. Derived by API Evangelist from AEMC's own production client bundle plus live anonymous probes of every route.
servers:
- url: https://energy-rules.aemc.gov.au/api/v1
  description: Production
tags:
- name: Rule Versions
  description: Versions of the National Electricity, Gas and Energy Retail Rules, with their published PDF and DOCX artefacts.
paths:
  /rules/{ruleType}/versions:
    get:
      operationId: listRuleVersions
      summary: List the published versions of a rule book
      description: 'Returns the paginated list of published versions of one rule book, newest first, each with its commencement and start dates, status flags and the full set of published PDF and DOCX files (full document, coversheet/contents and one file per chapter). Verified live 2026-07-27: `ner` returned 304 versions (latest v251), `ngr` 115 versions (latest v92), `nerr` 65 versions (latest v51); `nel` and the `-wa` variants returned an empty `data` array with a valid pagination envelope.'
      tags:
      - Rule Versions
      parameters:
      - name: ruleType
        in: path
        required: true
        description: Rule book identifier. Observed to carry data for `ner` (National Electricity Rules), `ngr` (National Gas Rules) and `nerr` (National Energy Retail Rules); `nel`, `ner-wa`, `ngr-wa`, `nerr-wa`, `wa` and `nogr` return HTTP 200 with an empty `data` array.
        schema:
          type: string
          examples:
          - ner
          - ngr
          - nerr
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: perPage
        in: query
        required: false
        description: Page size. The client defaults to 10 for the version list and 30 for search.
        schema:
          type: integer
          minimum: 1
          default: 30
      - name: showAll
        in: query
        required: false
        description: When true the full version history is returned in one response, ignoring `perPage` (observed 4.5 MB for `ner`).
        schema:
          type: boolean
      - name: searchVersion
        in: query
        required: false
        description: Filter by version number.
        schema:
          type: string
      - name: searchDate
        in: query
        required: false
        description: Return the version(s) in force on a date. Verified 2026-07-27 — `searchDate=2020-01-01` returned NER version 132.
        schema:
          type: string
          format: date
      - name: previewToken
        in: query
        required: false
        description: Editorial preview token. Not usable anonymously.
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of rule versions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RuleVersion'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      x-evidence:
        probed: '2026-07-27'
        requests:
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/ner/versions?page=1&perPage=1
          status: 200
          bytes: 13240
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/ngr/versions?perPage=1
          status: 200
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/nerr/versions?perPage=1
          status: 200
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/nel/versions?perPage=1
          status: 200
          note: empty data array
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/ner/versions?perPage=1&searchDate=2020-01-01
          status: 200
        - url: https://energy-rules.aemc.gov.au/api/v1/rules/ner/versions?perPage=1&showAll=true
          status: 200
          bytes: 4479473
components:
  schemas:
    PaginationLinks:
      type: object
      properties:
        first:
          type:
          - string
          - 'null'
          format: uri
        last:
          type:
          - string
          - 'null'
          format: uri
        prev:
          type:
          - string
          - 'null'
          format: uri
        next:
          type:
          - string
          - 'null'
          format: uri
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type:
          - integer
          - 'null'
        to:
          type:
          - integer
          - 'null'
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        path:
          type: string
          format: uri
        first_page_url:
          type:
          - string
          - 'null'
          format: uri
        last_page_url:
          type:
          - string
          - 'null'
          format: uri
        next_page_url:
          type:
          - string
          - 'null'
          format: uri
        prev_page_url:
          type:
          - string
          - 'null'
          format: uri
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type:
                - string
                - 'null'
                format: uri
              label:
                type: string
              active:
                type: boolean
    RuleVersion:
      type: object
      properties:
        id:
          type: integer
          description: Version id used as the path parameter on every other endpoint.
        version:
          type: integer
          description: Human-facing rule version number.
        type:
          type: string
          examples:
          - ner
          - ngr
          - nerr
        files:
          type: object
          properties:
            pdf:
              type: array
              items:
                $ref: '#/components/schemas/RuleFile'
            docx:
              type: array
              items:
                $ref: '#/components/schemas/RuleFile'
        commencement_date:
          type:
          - string
          - 'null'
        start_date:
          type:
          - string
          - 'null'
        schedule_date:
          type:
          - string
          - 'null'
        end_date:
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
        parsed:
          type: integer
        approved:
          type: integer
        archived:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        hash:
          type: string
          description: Content hash used in the S3 asset path for this version's files.
        added_coversheets:
          type: integer
        is_current:
          type: integer
        pdf_coversheet:
          type:
          - string
          - 'null'
        docx_coversheet:
          type:
          - string
          - 'null'
        is_historic_data:
          type: integer
        links:
          type: object
          properties:
            toc:
              type: string
              format: uri
            chapters:
              type: string
              format: uri
    RuleFile:
      type: object
      description: A published rule artefact on AEMC's S3 bucket (aemc-dra-production-s3.s3.ap-southeast-2.amazonaws.com).
      properties:
        name:
          type: string
        path:
          type: string
          format: uri
        size:
          type: integer
        filename:
          type: string