# Connector: SEC EDGAR filings (`edgar`)
**Purpose**: regulatory filings of US-listed issuers (and foreign private issuers filing 6-K/20-F/40-F) from
the official submissions API `https://data.sec.gov/submissions/CIK##########.json`. An 8-K with item 2.02 (results),
5.02 (executive departure), 1.05 (material cybersecurity incident), 1.01 (material agreement), a 10-K/10-Q, an S-1,
a 13D or a DEF 14A becomes a `filing` list event on the company entity, with a direct link to the primary document.
**Sensor types**: REST_API, JSON. **Config**: `forms?: ["8-K","10-K",…]` (whitelist), `excludeForms?`
(default: insider forms 3/4/5 and 144 — hundreds per quarter for large caps), `maxItems?` (60).
**Normalization**: the API is columnar (`filings.recent.form[]`, `accessionNumber[]`…); the connector rebuilds one
item per filing keyed by accession number: `form`, `formLabel` (decoded), `items` (8-K item numbers → labels),
`filingDate`, `publishedAt` (acceptance time), `url` (Archives document), `indexUrl`, `xbrl`. `compareFields:
[form, items]`. `extra`: CIK, tickers, exchanges, SIC, fiscal year end, state of incorporation.
**Rules of the road** (sec.gov/developer): descriptive User-Agent with contact e-mail (`WS_EDGAR_USER_AGENT`,
default `WebSensor (contact@websensor.io)`), ≤ 10 req/s across all sensors. With per-host concurrency 2 and tier B/C
intervals the engine stays far below. `Host: data.sec.gov` is sent explicitly (the API refuses some clients otherwise).
**Finding a CIK**: `https://www.sec.gov/files/company_tickers.json` (ticker → CIK), or
`https://efts.sec.gov/LATEST/search-index?keysTyped=<name>`; pad to 10 digits.
**Known quirks**: `filings.recent` holds up to ~1000 filings, older ones live in `filings.files[]` (not fetched);
acceptance time is US/Eastern converted to UTC by the API; 6-K items are empty (foreign issuers).
**Tests**: `connectors2.test.ts` (columnar → items, form filter, 8-K decoding). **Verified**: 2026-09-08 (Apple CIK 320193).