Ontario Energy Board Records API

openapi: 3.2.0
info:
  title: OEB Regulatory Document Search (RDS) Records API
  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.
  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
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.
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
components:
  schemas:
    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.
    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
    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
    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".
    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
    TrimStringProperty:
      type: object
      properties:
        __type:
          type: string
          example: HP.HPTRIM.ServiceModel.TrimStringProperty, TRIMServiceAPIModel
        Value:
          type: string
      required:
      - Value
    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'
  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
externalDocs:
  description: OEB Regulatory Document Search (human entry point)
  url: https://www.oeb.ca/rds