openapi: 3.1.0
info:
title: FERC eForms (eCollection) 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.
- name: Taxonomy
description: XBRL taxonomy versions, packages and sample forms for the FERC eForms.
- name: Filing
description: Credentialed machine-to-machine submission of XBRL filings.
- name: Reference
description: Form lists and submission constraints.
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
/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
/SubmissionHistory/forms:
get:
tags: [Reference]
operationId: listForms
summary: List the eForms form names and identifiers
description: >-
Returns the form names, their numeric identifiers, and which identifiers are annual forms.
security: []
responses:
'200':
description: Form reference lists.
content:
application/json:
schema:
$ref: '#/components/schemas/FormList'
x-evidence:
probed: '2026-07-27'
status: 200
authentication: none
/getTestStatus:
get:
tags: [Reference]
operationId: getTestStatus
summary: Get submission constraints and test-mode status
description: >-
Returns whether the environment is in test status plus the submission constraints the filing
client enforces — maximum XBRL name length, maximum file name length, maximum file size in
bytes, and the allowed additional-file tags.
security: []
responses:
'200':
description: Submission constraints.
content:
application/json:
schema:
$ref: '#/components/schemas/TestStatus'
x-evidence:
probed: '2026-07-27'
status: 200
authentication: none
/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
/faq:
get:
tags: [Reference]
operationId: listFaq
summary: List eForms portal FAQ entries
security: []
responses:
'200':
description: FAQ entries. Observed as an empty array on 2026-07-27.
content:
application/json:
schema:
type: array
items:
type: object
x-evidence:
probed: '2026-07-27'
status: 200
body: '[]'
authentication: none
/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
/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:
securitySchemes:
filerBearer:
type: http
scheme: bearer
description: >-
Bearer token issued by POST /token via the OAuth 2.0 password grant with role=filer.
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
FormList:
type: object
properties:
formList:
type: array
items:
type: string
formIDList:
type: array
items:
type: integer
annualForms:
type: array
items:
type: integer
TestStatus:
type: object
properties:
status:
type: boolean
maxAllowedXbrlName:
type: integer
maxAllowedFileName:
type: integer
maxAllowedFileSize:
type: integer
description: Bytes.
allowedFileTags:
type: string
showReleaseNotesButton:
type: boolean
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