openapi: 3.2.0
info:
  title: FERC eForms (eCollection) Filing 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: Filing
  description: Credentialed machine-to-machine submission of XBRL filings.
paths:
  /token:
    post:
      tags:
      - Filing
      operationId: getFilerToken
      summary: Exchange FERC eRegistration credentials for a bearer token
      description: OAuth 2.0 Resource Owner Password Credentials grant (RFC 6749 section 4.3). Credentials are the filer's FERC eRegistration / Company Registration username (email) and password; the filer must be authorized to submit for the company. Documented in FERC's Postman collection and step-by-step guide.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - username
              - password
              - grant_type
              - role
              properties:
                username:
                  type: string
                  description: Email address of the filer, eligible to submit for the company.
                password:
                  type: string
                  format: password
                grant_type:
                  type: string
                  const: password
                role:
                  type: string
                  const: filer
      responses:
        '200':
          description: Bearer token issued.
        '400':
          description: 'Grant or credential failure. Observed bodies: `{"error":"unsupported_grant_type"}` on a GET/empty body, and `{"error":"Failed validating user in company registration"}` for an unregistered filer.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      x-evidence:
        probed: '2026-07-27'
        method: GET (no body)
        status: 400
        body: '{"error":"unsupported_grant_type"}'
        source: collections/ferc-xbrl-submission-api.postman_collection.json
  /SubmissionHistory/ExternalFiling:
    post:
      tags:
      - Filing
      operationId: postExternalFiling
      summary: Submit a zipped XBRL filing
      description: Machine-to-machine submission of a FERC eForms XBRL filing. Requires the bearer token from POST /token. Parameter semantics and the numeric form mapping are taken verbatim from FERC's published step-by-step guide.
      security:
      - filerBearer: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - zipFiling
              - cid
              - reportYear
              - reportPeriod
              - email
              - form
              properties:
                zipFiling:
                  type: string
                  format: binary
                  description: Zip archive containing the XBRL instance and any additional files required by the XBRL specification. Only the .zip extension is accepted.
                cid:
                  type: string
                  description: Company CID from FERC Company Registration, e.g. C006939.
                  examples:
                  - C006939
                reportYear:
                  type: string
                  description: Four-digit report year the filing is made for.
                reportPeriod:
                  type: string
                  description: Q1, Q2 or Q3 for quarterly forms; Q4 for annual forms.
                  enum:
                  - Q1
                  - Q2
                  - Q3
                  - Q4
                email:
                  type: string
                  format: email
                  description: Email address of the filer, eligible to submit for the company.
                form:
                  type: string
                  description: Numeric form identifier. Published mapping — Form 1:1, Form 1F:2, Form 3Q Electric:3, Form 2:4, Form 2A:5, Form 3Q Natural Gas:6, Form 6:7, Form 6Q:8, Form 60:9, Form 714:10.
                  enum:
                  - '1'
                  - '2'
                  - '3'
                  - '4'
                  - '5'
                  - '6'
                  - '7'
                  - '8'
                  - '9'
                  - '10'
                test:
                  type: string
                  description: Indicate whether this is a test submission.
                  enum:
                  - 'true'
                  - 'false'
                additionalNotes:
                  type: string
                  description: Notes accompanying the submission.
      responses:
        '200':
          description: Submission accepted for processing.
        '401':
          description: Missing or invalid bearer token.
      x-evidence:
        probed: false
        note: Write endpoint against production regulatory filing; deliberately NOT exercised. Described from FERC's published Postman collection and step-by-step guide only.
        source: https://www.ferc.gov/vendor-files-library
  /claims:
    get:
      tags:
      - Filing
      operationId: getFilerClaims
      summary: Get the authenticated filer's claims
      description: Credentialed. Returns 401 `{"message":"Authorization has been denied for this request."}` anonymously; the response body for an authenticated caller was not observed and is deliberately not described.
      security:
      - filerBearer: []
      responses:
        '200':
          description: Filer claims. Shape not observed.
        '401':
          description: Authorization denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-evidence:
        probed: '2026-07-27'
        status: 401
  /SubmissionHistory:
    get:
      tags:
      - Filing
      operationId: listFilerSubmissionHistory
      summary: List the authenticated filer's submission history
      description: Credentialed. Returns 401 anonymously; the authenticated response shape was not observed and is deliberately not described.
      security:
      - filerBearer: []
      responses:
        '200':
          description: Filer submission history. Shape not observed.
        '401':
          description: Authorization denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-evidence:
        probed: '2026-07-27'
        status: 401
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
  securitySchemes:
    filerBearer:
      type: http
      scheme: bearer
      description: Bearer token issued by POST /token via the OAuth 2.0 password grant with role=filer.