FERC Taxonomy API

openapi: 3.2.0
info:
  title: FERC eForms (eCollection) Taxonomy 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: Taxonomy
  description: XBRL taxonomy versions, packages and sample forms for the FERC eForms.
paths:
  /TaxonomyHistory:
    get:
      tags:
      - Taxonomy
      operationId: listTaxonomyHistory
      summary: List published XBRL taxonomy versions
      description: Returns every published FERC eForms XBRL taxonomy version with the reporting window it applies to and the schema (.xsd) URLs for each form in the release. Answers anonymously. Observed 2026-07-27 returning 25 versions across Form 1, Form 2, Form 6, Form 60 and Form 714.
      security: []
      responses:
        '200':
          description: Taxonomy version history.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxonomyVersion'
      x-evidence:
        probed: '2026-07-27'
        status: 200
        record_count: 25
        authentication: none
  /TaxonomyHistory/TaxonomyFile/{versionID}:
    get:
      tags:
      - Taxonomy
      operationId: getTaxonomyFile
      summary: Download the taxonomy file bundle for a version
      security: []
      parameters:
      - name: versionID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Zip archive.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      x-evidence:
        probed: '2026-07-27'
        status: 200
        bytes: 1509992
        authentication: none
  /TaxonomyHistory/SampleForm/{versionID}:
    get:
      tags:
      - Taxonomy
      operationId: getTaxonomySampleForm
      summary: Download the sample/blank rendered form bundle for a taxonomy version
      security: []
      parameters:
      - name: versionID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Zip archive.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      x-evidence:
        probed: '2026-07-27'
        status: 200
        bytes: 462378
        authentication: none
  /TaxonomyHistory/getReleaseFiles:
    get:
      tags:
      - Taxonomy
      operationId: getTaxonomyReleaseFiles
      summary: Get the taxonomy release notes document
      description: Returns a base64-encoded PDF of the current taxonomy release notes.
      security: []
      responses:
        '200':
          description: Base64-encoded PDF document.
          content:
            application/json:
              schema:
                type: string
                contentEncoding: base64
                contentMediaType: application/pdf
      x-evidence:
        probed: '2026-07-27'
        status: 200
        bytes: 455998
        authentication: none
  /TaxonomyRevision:
    get:
      tags:
      - Taxonomy
      operationId: listTaxonomyRevisions
      summary: List taxonomy revisions (administrative)
      description: Credentialed. Returns 401 anonymously; authenticated shape not observed.
      security:
      - filerBearer: []
      responses:
        '200':
          description: Taxonomy revisions. 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:
    TaxonomyVersion:
      type: object
      properties:
        versionID:
          type: integer
        formID:
          type:
          - integer
          - 'null'
        formName:
          type: string
        startYear:
          type: integer
        startPeriod:
          type: string
        endYear:
          type:
          - integer
          - 'null'
        endPeriod:
          type:
          - string
          - 'null'
        version:
          type: string
          description: Taxonomy version date, e.g. 2026-04-01.
        versionCount:
          type:
          - integer
          - 'null'
        publishString:
          type: string
          description: JSON-encoded string of the published schema URLs for the release, keyed url0, url1, ...
        revisionNumber:
          type: integer
    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.