openapi: 3.1.0
info:
  title: OEB Regulatory Document Search (RDS)
  version: 2026-07-27
  summary: Anonymous, undocumented JSON query surface over the Ontario Energy Board's regulatory document record.
  description: >-
    A machine-readable description of the query surface the Ontario Energy Board's Regulatory
    Document Search (RDS) actually serves at https://www.rds.oeb.ca/CMWebDrawer.


    IMPORTANT — PROVENANCE. The OEB does **not** publish this definition. The OEB publishes no API
    reference, no base-URI statement, no query-syntax documentation, no OpenAPI, no rate-limit policy
    and no terms for this interface. RDS runs on Micro Focus / OpenText Content Manager WebDrawer, and
    the JSON projection described here is default behaviour of that product, reached by adding
    `format=json` to the same parameterised `Record` URLs the OEB itself links to from www.oeb.ca
    (the licensed-companies list alone links hundreds of them). This document was **generated by API
    Evangelist from live anonymous probes on 2026-07-27** — every path, parameter, status code, media
    type and schema below was observed, and each operation carries an `x-evidence` block naming the
    exact URL probed and what came back. Nothing here is inferred from documentation, because there is
    none. Treat it as an accurate map of an undocumented, unsupported surface that the OEB may change
    or withdraw without notice — not as an offered API contract.


    Authentication: none. Every request below was made anonymously with no key, no token, no cookie
    and no signup.
  contact:
    name: Ontario Energy Board
    url: https://www.oeb.ca/contact-ontario-energy-board
  license:
    name: Open Government Licence – Ontario
    url: https://www.ontario.ca/page/open-government-licence-ontario
  x-generated-by: API Evangelist enrichment pipeline
  x-generation-method: generated-from-live-probes
  x-published-by-provider: false
externalDocs:
  description: OEB Regulatory Document Search (human entry point)
  url: https://www.oeb.ca/rds
servers:
  - url: https://www.rds.oeb.ca/CMWebDrawer
    description: Production RDS WebDrawer host (TLSv1.3, HSTS max-age 31536000; includeSubDomains; preload)
tags:
  - name: Records
    description: Search and retrieve records (filings, decisions, orders, licences, correspondence) in the OEB case record.
  - name: Search Metadata
    description: The machine-readable query vocabulary the RDS search form itself loads.
paths:
  /Record:
    get:
      tags: [Records]
      operationId: searchRecords
      summary: Search the OEB regulatory document record
      description: >-
        Runs a Content Manager record search and returns matching records. With `format=json` the
        response is a Content Manager `TRIMServiceAPIModel` payload; without it the same query renders
        an HTML results page. Results carry the OEB's own regulatory fields — CaseNumber,
        SIDocumentType, Applicant, EnergyType, PrimaryApplicationType, DateIssued, fDateReceived.
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Search clause. Use `<term>=<value>` for comparison or `<term>:<value>` for word/contains
            matching. The complete set of 303 valid terms is published live at
            /Help/WDSearchClauseDefJS?trimType=Record and captured in
            vocabulary/ontario-energy-board-rds-search-clauses.yml.
          schema:
            type: string
          examples:
            byCaseNumber:
              summary: Every document filed in one case (verified 200, 40 records)
              value: CaseNumber=EB-2021-0183
            byEnergyType:
              summary: All electricity records (verified 200, 131,171 records)
              value: EnergyType=Electricity
            byApplicationType:
              summary: All Initiatives records (verified 200, 22,160 records)
              value: PrimaryApplicationType=Initiatives
            byFreeText:
              summary: Word search across the record (verified 200, 4,276 records)
              value: anyWord:rate
        - name: format
          in: query
          required: false
          description: Response projection. `json` returns application/json; omitted returns the HTML results page.
          schema:
            type: string
            enum: [json]
          example: json
        - name: sortBy
          in: query
          required: false
          description: >-
            Sort clause; a trailing `-` sorts descending. 87 of the 303 clauses are sortable
            (`CanSort: true` in the clause definitions). This is the parameter the OEB's own website
            links use.
          schema:
            type: string
          example: recRegisteredOn-
        - name: pageSize
          in: query
          required: false
          description: Number of records returned in this page. Values from 1 to 400 were observed in OEB-authored links.
          schema:
            type: integer
            minimum: 1
          example: 400
        - name: start
          in: query
          required: false
          description: 1-based index of the first record to return; the paging cursor for `pageSize`.
          schema:
            type: integer
            minimum: 1
          example: 2
      responses:
        '200':
          description: >-
            Search executed. NOTE — a rejected or malformed clause also returns 200 with an empty
            `Results` array and the reason in plain English in `SearchTitle`, not an HTTP error status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSearchResponse'
              examples:
                caseSearch:
                  summary: Two records from case EB-2021-0183
                  externalValue: examples/ontario-energy-board-rds-record-search-response.json
                unknownClause:
                  summary: Unknown search method — HTTP 200 with the error in SearchTitle
                  externalValue: examples/ontario-energy-board-rds-error-unknown-search-method.json
            text/html:
              schema:
                type: string
                description: HTML results page returned when `format` is omitted.
      x-evidence:
        probed: '2026-07-27'
        requests:
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=CaseNumber=EB-2021-0183&sortBy=recRegisteredOn-&pageSize=2&format=json
            status: 200
            content_type: application/json; charset=utf-8
            note: TotalResults 40, HasMoreItems true
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=CaseNumber=EB-2021-0183&format=json&pageSize=1&start=2
            status: 200
            content_type: application/json; charset=utf-8
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=EnergyType=Electricity&format=json&pageSize=1
            status: 200
            note: TotalResults 131171
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=anyWord:rate&format=json&pageSize=1
            status: 200
            note: TotalResults 4276
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=NotAField=zzz&format=json&pageSize=1
            status: 200
            note: >-
              Empty Results; SearchTitle "You have specified an unknown search method 'NotAField'."
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record?q=CaseNumber=EB-2021-0183&format=xml&pageSize=1
            status: 403
            content_type: application/xml
            note: XML projection is refused; only the JSON and HTML projections are open.
  /Record/{uri}:
    get:
      tags: [Records]
      operationId: getRecord
      summary: Retrieve a single record by Content Manager URI
      description: >-
        Record detail by URI. Observed to fail for an anonymous caller — the server attempts to
        resolve `RecordContainer` and returns HTTP 500 carrying a `TrimException` in `ResponseStatus`.
        The document bytes are nevertheless reachable anonymously through the `/File/document`
        sub-resource below. Recorded because it was probed, not because it works.
      parameters:
        - $ref: '#/components/parameters/RecordUri'
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json]
      responses:
        '500':
          description: TrimException — "Error retrieving data for property RecordContainer. Access denied."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSearchResponse'
              examples:
                accessDenied:
                  externalValue: examples/ontario-energy-board-rds-error-500-access-denied.json
            text/html:
              schema:
                type: string
      x-evidence:
        probed: '2026-07-27'
        requests:
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record/891285?format=json
            status: 500
            content_type: application/json; charset=utf-8
            note: 'ResponseStatus.ErrorCode TrimException, Meta.TrimErrorCode 22760'
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record/891285
            status: 500
            content_type: text/html
  /Record/{uri}/File/document:
    get:
      tags: [Records]
      operationId: downloadRecordDocument
      summary: Download the document filed under a record
      description: >-
        Returns the underlying filed document — overwhelmingly PDF, with MSG, DOC and XLS also present
        in the record (`RecordExtension` on each search hit tells you which). Anonymous, no key.
      parameters:
        - $ref: '#/components/parameters/RecordUri'
      responses:
        '200':
          description: The document bytes.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: No such record, or the record has no electronic document. Returns the WebDrawer HTML error page, not JSON.
          content:
            text/html:
              schema:
                type: string
      x-evidence:
        probed: '2026-07-27'
        requests:
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record/891285/File/document
            status: 200
            content_type: application/pdf
            bytes: 339517
          - url: https://www.rds.oeb.ca/CMWebDrawer/Record/999999999/File/document
            status: 404
            content_type: text/html
  /Help/WDSearchClauseDefJS:
    get:
      tags: [Search Metadata]
      operationId: getSearchClauseDefinitions
      summary: The full query vocabulary accepted by the q parameter
      description: >-
        Returns a JavaScript document declaring `var searchClauses = [...]` — 303 clause definitions
        with InternalName, Name, MethodGroup, ObjectTypeParameter, ParameterFormat, CanSort and
        Caption. This is the only machine-readable description of the RDS query language that exists;
        the RDS search form loads it to build its own dropdowns. Parsed into
        vocabulary/ontario-energy-board-rds-search-clauses.yml.
      parameters:
        - name: trimType
          in: query
          required: true
          schema:
            type: string
            enum: [Record]
          example: Record
      responses:
        '200':
          description: JavaScript source declaring the searchClauses array.
          content:
            text/javascript:
              schema:
                type: string
      x-evidence:
        probed: '2026-07-27'
        requests:
          - url: https://www.rds.oeb.ca/CMWebDrawer/Help/WDSearchClauseDefJS?trimType=Record
            status: 200
            content_type: text/javascript
            bytes: 72885
            note: 303 clauses parsed, 62 of them OEB-specific Additional Fields, 87 sortable.
  /EnumItemJS:
    get:
      tags: [Search Metadata]
      operationId: getSearchClauseEnums
      summary: Labels for the search clause groups and special date values
      description: Returns a JavaScript document declaring `var enums = {...}` with the display labels for each clause group.
      parameters:
        - name: Enums
          in: query
          required: true
          description: Comma-separated enum names.
          schema:
            type: string
          example: SearchClauseGroup,SpecialDates
      responses:
        '200':
          description: JavaScript source declaring the enums object.
          content:
            text/javascript:
              schema:
                type: string
      x-evidence:
        probed: '2026-07-27'
        requests:
          - url: https://www.rds.oeb.ca/CMWebDrawer/EnumItemJS?Enums=SearchClauseGroup,SpecialDates
            status: 200
            content_type: text/javascript
            bytes: 1441
components:
  parameters:
    RecordUri:
      name: uri
      in: path
      required: true
      description: Content Manager record URI, an opaque integer returned as `Uri` on every search hit.
      schema:
        type: integer
      example: 891285
  schemas:
    RecordSearchResponse:
      type: object
      description: Content Manager ServiceAPIModel search payload, as observed on 2026-07-27.
      properties:
        Results:
          type: array
          items:
            $ref: '#/components/schemas/Record'
        PropertiesAndFields:
          type: object
          description: Empty object in every observed response.
        TotalResults:
          type: integer
          description: Total records matching the clause, irrespective of pageSize.
        CountStringEx:
          type: string
          description: Human-readable count, e.g. "40 records".
        MinimumCount:
          type: integer
        Count:
          type: integer
        HasMoreItems:
          type: boolean
        SearchTitle:
          type: string
          description: >-
            Human-readable description of the executed search — and, when the clause is invalid, the
            plain-English error message. Read this even on HTTP 200.
        HitHighlightString:
          type: string
        TrimType:
          type: string
          example: Record
        ResponseStatus:
          $ref: '#/components/schemas/ResponseStatus'
      required: [Results, TotalResults, TrimType, ResponseStatus]
    Record:
      type: object
      description: One record — a filing, decision, order, licence or piece of correspondence.
      properties:
        Uri:
          type: integer
          description: Opaque record identifier; the key for /Record/{uri}/File/document.
        TrimType:
          type: string
          example: Record
        RecordTitle:
          $ref: '#/components/schemas/TrimStringProperty'
        RecordExtension:
          $ref: '#/components/schemas/TrimStringProperty'
        RecordDateModified:
          $ref: '#/components/schemas/TrimDateTime'
        Fields:
          $ref: '#/components/schemas/RecordFields'
      required: [Uri, TrimType]
    RecordFields:
      type: object
      description: >-
        The OEB's own user-defined regulatory fields. Which fields appear depends on the record; the
        set below was returned by every observed search hit.
      properties:
        CaseNumber:
          allOf:
            - $ref: '#/components/schemas/TrimStringProperty'
          description: OEB case number, e.g. EB-2021-0183.
        SIDocumentType:
          allOf:
            - $ref: '#/components/schemas/TrimStringProperty'
          description: Document type, e.g. "Decision and Order on Cost Awards", "Correspondence".
        Applicant:
          $ref: '#/components/schemas/LocationRef'
        EnergyType:
          allOf:
            - $ref: '#/components/schemas/TrimStringProperty'
          description: Electricity or Natural Gas.
        PrimaryApplicationType:
          allOf:
            - $ref: '#/components/schemas/TrimStringProperty'
          description: e.g. Initiatives, Rates, Licensing.
        DateIssued:
          $ref: '#/components/schemas/TrimDateTime'
        fDateReceived:
          allOf:
            - $ref: '#/components/schemas/TrimDateTime'
          description: Date received by the OEB.
    TrimStringProperty:
      type: object
      properties:
        __type:
          type: string
          example: 'HP.HPTRIM.ServiceModel.TrimStringProperty, TRIMServiceAPIModel'
        Value:
          type: string
      required: [Value]
    TrimDateTime:
      type: object
      description: >-
        Content Manager date. `IsClear: true` with DateTime 0001-01-01T00:00:00.0000000Z means the
        date is unset — treat it as null, not as the year 1.
      properties:
        __type:
          type: string
          example: 'HP.HPTRIM.ServiceModel.TrimDateTime, TRIMServiceAPIModel'
        IsClear:
          type: boolean
        IsTimeClear:
          type: boolean
        DateTime:
          type: string
          format: date-time
        StringValue:
          type: string
          description: Localised rendering, e.g. "2025-03-04 at 5:06 PM".
    LocationRef:
      type: object
      description: Reference to a Content Manager Location (a party — applicant, intervenor, the OEB itself).
      properties:
        __type:
          type: string
          example: 'HP.HPTRIM.ServiceModel.LocationRef, TRIMServiceAPIModel'
        LocationFormattedName:
          $ref: '#/components/schemas/TrimStringProperty'
        TrimType:
          type: string
          example: Location
        Uri:
          type: integer
    ResponseStatus:
      type: object
      description: >-
        Empty object on success. On failure it carries the Content Manager exception — this is the
        error envelope, and it is NOT RFC 9457 problem+json.
      properties:
        ErrorCode:
          type: string
          example: TrimException
        Message:
          type: string
          example: Error retrieving data for property RecordContainer. Access denied.
        Errors:
          type: array
          items:
            type: object
        Meta:
          type: object
          properties:
            TrimErrorCode:
              type: string
              example: '22760'