FERC Public Filings API

openapi: 3.2.0
info:
  title: FERC eForms (eCollection) Public Filings API
  version: '2026-07-27'
  description: 'Machine-readable description of the FERC eForms XBRL API hosted at https://ecollection.ferc.gov/api. FERC publishes NO OpenAPI for this API. This document is DERIVED, not harvested: every path below is a literal URL string taken from FERC''s own shipped production JavaScript bundle (https://ecollection.ferc.gov/main.6c69ecbce3fd46f494eb.js, `environment.apiURL = "https://eCollection.ferc.gov/api/"`), or from FERC''s published Postman collection and Submission API step-by-step guide, and each was probed live on 2026-07-27 with the HTTP status recorded in `x-evidence`. Response schemas are derived ONLY from responses actually observed on those probes — no field is invented. Endpoints that answered 401 are described by path and method only, with no invented request or response body.


    Two surfaces live here. (1) An ANONYMOUS PUBLIC READ surface — the public submission history of every FERC eForms filing, per-filing detail, the XBRL taxonomy version history and taxonomy packages, the form list, and the submission constraints — none of which is advertised on data.ferc.gov or in FERC''s developer documentation. (2) The CREDENTIALED WRITE surface — the OAuth2 password-grant token endpoint and the external filing endpoint documented in FERC''s vendor files library for regulated filers.


    PERSONAL DATA NOTICE: GET /PublicSubmissionHistory returns a `filerEmail` field carrying the work email address of the individual who submitted each filing, served anonymously with no authentication. The field is documented here structurally; no example in this repository carries a real value, and no agent skill or MCP tool in this repository is built on this endpoint.'
  contact:
    name: FERC Online Support
    url: https://www.ferc.gov/ferc-online/overview
  license:
    name: U.S. Government Work (public domain, 17 U.S.C. 105)
    url: https://data.ferc.gov/disclaimer/
  x-provenance:
    generated: '2026-07-27'
    method: derived
    sources:
    - https://ecollection.ferc.gov/main.6c69ecbce3fd46f494eb.js
    - collections/ferc-xbrl-submission-api.postman_collection.json
    - https://www.ferc.gov/sites/default/files/2020-12/FERC_SubmissionAPI_PROD-Step-by-step-guide_v3.1.pdf
    - live HTTP probes 2026-07-27
    note: Not published by FERC. Derived by API Evangelist from FERC's own production client bundle plus live anonymous probes. Report inaccuracies rather than treating this as an authoritative contract.
servers:
- url: https://ecollection.ferc.gov/api
  description: Production
tags:
- name: Public Filings
  description: Anonymous read access to the public FERC eForms submission record.
paths:
  /PublicSubmissionHistory:
    get:
      tags:
      - Public Filings
      operationId: listPublicSubmissionHistory
      summary: List the public FERC eForms submission history
      description: Returns the complete public record of eForms submissions. Answers anonymously with no API key and no token. Observed 2026-07-27 returning 37,588 records in a single 10.6 MB JSON array with no pagination. A `formID` query parameter appears in FERC's client but the observed response was identical in size with and without it.
      security: []
      parameters:
      - name: formID
        in: query
        required: false
        schema:
          type: integer
        description: Form identifier (1-10). Observed to have no effect on the anonymous response.
      responses:
        '200':
          description: Array of public submission records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicSubmission'
      x-evidence:
        probed: '2026-07-27'
        status: 200
        record_count: 37588
        bytes: 10677047
        authentication: none
  /SubmissionDetail/{filingID}:
    get:
      tags:
      - Public Filings
      operationId: getSubmissionDetail
      summary: Get the detail and attachment manifest for one filing
      description: Returns the accession number, additional notes, CPA certification flags and the attachment manifest (XBRL instance file and HTML rendering) for a single filing. Answers anonymously.
      security: []
      parameters:
      - name: filingID
        in: path
        required: true
        schema:
          type: integer
        description: filingID from GET /PublicSubmissionHistory.
      responses:
        '200':
          description: Submission detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionDetail'
      x-evidence:
        probed: '2026-07-27'
        status: 200
        authentication: none
components:
  schemas:
    PublicSubmission:
      type: object
      description: One public eForms filing record. Field set observed verbatim on 2026-07-27; no field added.
      properties:
        filingID:
          type: integer
        cid:
          type: string
          description: FERC Company Registration company identifier, e.g. C0#####.
        companyName:
          type: string
        formName:
          type: string
          description: e.g. "Form 1", "Form 3Q Electric", "Form 714".
        year:
          type: integer
        period:
          type: string
          description: Q1, Q2, Q3 or Q4.
        submittedOn:
          type: string
          format: date-time
        status:
          type: string
          description: e.g. "Accepted".
        isConfidential:
          type: boolean
        isTestSubmission:
          type: string
          description: e.g. "Not Test".
        filerEmail:
          type: string
          format: email
          description: PERSONAL DATA. The work email address of the individual filer, served anonymously. Do not harvest; no example value is recorded in this repository.
          x-personal-data: true
    SubmissionDetail:
      type: object
      properties:
        additionalNotes:
          type: string
        accessionNumber:
          type: string
          description: FERC accession number, e.g. 20260727-8000.
        privilegedAccessionNumber:
          type:
          - string
          - 'null'
        attachments:
          type: array
          items:
            type: object
            properties:
              fileID:
                type: integer
              fileType:
                type: string
                description: e.g. XBRL_INSTANCE_FILE, HTML_RENDERING.
              fileName:
                type: string
              isConfidential:
                type: boolean
              fileBlob:
                type: string
        cpaCertRequired:
          type: boolean
        cpaCertUploaded:
          type: boolean
        isFiledThrougheForms:
          type: boolean
  securitySchemes:
    filerBearer:
      type: http
      scheme: bearer
      description: Bearer token issued by POST /token via the OAuth 2.0 password grant with role=filer.