# Main API Stream — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 3fcd804c
> Fetch this file at: https://uat.finradarapi.com/llms/main-api-stream.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Main API Stream

Real-time feed of new SEC filings.

### WS WebSocket (Namespace: /sec)

Listen for new SEC filings (10-K, 8-K, 4, etc.) as they are ingested.

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Always the literal string `"new_filing"` for individual-filing events. For batch events the per-row event field is omitted — the wrapping event name is `new_filings_batch` and each row is a FilingObject.
- `accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Use as a deduplication key client-side — same filing will NOT be re-emitted within a session, but reconnects may replay the last few minutes.
- `cik` (string): Filer CIK in 10-character zero-padded form. Use for client-side per-issuer filtering (e.g. only process filings from your watchlist of CIKs).
- `ticker` (string (nullable)): Resolved ticker from CIK→ticker lookup at filing time (canonical hyphen form). Null when the filer has no public-equity ticker. Useful as the primary filter key for trading-desk consumers.
- `form_type` (string): Canonical form type (`4`, `8-K`, `10-K`, `13F-HR`, `S-1`, etc.). Subscribe to per-form-type rooms (`join: form_4`) to filter server-side and reduce event volume.
- `filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date in ET. Distinct from `accepted_at` — `filed_date` is the calendar date for compliance/UI display; `accepted_at` is the precise timestamp.
- `accepted_at` (string): ISO-8601 UTC timestamp of SEC EDGAR's acceptance moment. Use for intra-day ordering and latency measurement (compare against your client receipt time — should typically be < 60 seconds).
- `filing_url` (string): Canonical SEC EDGAR URL for the filing's index page. Use as the human-readable link in dashboards; for programmatic content access drill into `/api/v1/sec/filings/{accession_number}/html` or `/scrapping/extractor`.

**Since:** v1.0.0

**Utility:** Real-time push stream of newly-accepted SEC filings — connect once via Socket.IO and receive every filing as it lands in our DB (typically within 30-60 seconds of EDGAR acceptance). Drop-in replacement for sec-api.io's WebSocket: same event shape, same field naming, same per-form-type subscription model. The right choice for low-latency trading workflows that need filing-level signals (8-Ks for material events, Form 4s for insider trades, 13D/G for ownership changes) faster than polling the REST endpoints can deliver. Per-form-type rooms (e.g. `join: form_4`) let you filter server-side rather than receiving the firehose. The 100-token cost is a FLAT per-UTC-day connection fee — reconnects on the same UTC day are free, so disconnects (network blips, deploys) don't multiply your costs. For per-message billing semantics, no charge per event — just the daily connection fee.

**Use case:** Triggering an analysis pipeline instantly when a specific company files an 8-K.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query (logs in access logs). 100-token/day fee on first connect of the UTC day. Free-tier OK. `?token=` removed v3.20.2.
- `namespace` (config, required, default: /sec): Socket.IO namespace to connect to. `/sec` is the canonical SEC-filings stream. The connection URL is `<base>/socket.io/?EIO=4&transport=websocket` and the namespace is selected via Socket.IO client API (`io('/sec')`), NOT via URL path.

**Events (server → client):**
- `connect`: Connection established. No payload — fire your `subscribe` action next to filter the firehose.
- `new_filings_batch`: Batch of new filings (1-50 entries). Payload: `Array<FilingObject>` where each FilingObject has the shape described in `responseSchema`. Server batches multiple-filing-bursts into one event when they land within 100ms of each other.

**Sample response:**
```json
{
  "event": "new_filing",
  "accession_number": "0001127602-26-001234",
  "cik": "0000320193",
  "ticker": "AAPL",
  "form_type": "4",
  "filed_date": "2026-05-01",
  "accepted_at": "2026-05-01T20:14:32.000Z",
  "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193"
}
```