# SEC Filings API — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: e3277222
> Fetch this file at: https://uat.finradarapi.com/llms/sec-filings-api.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.

---

## SEC Filings API

Core access to 25+ years of SEC filings.

### GET /api/v1/sec/filings

List filings with pagination and filtering. When querying by ticker, if no local filings exist yet, the API automatically backfills the complete filing history from SEC EDGAR (first call may take a few seconds).

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — present on every endpoint that wraps via `ApiResponse.paginated()`. Use to assert the call succeeded before reading `data`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs to trace the exact request lifecycle (gateway routing, auth resolution, token debit, response).
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`). Use as the freshness marker — auto-backfill calls that take a few seconds will surface here as a measurable lag from your client-side `Date.now()`.
- `data` (array): Array of filing rows matching the query, sorted by `filed_date DESC` by default (newest first; configurable via `sort` param). Empty array when no rows match — never null. One element per filing — see `data[].*` for shape.
- `data[].id` (integer): Internal `sec_filing_entries.id` row ID (auto-increment primary key). Stable across calls but not portable across environments — always join via `accession_number` for cross-environment work.
- `data[].accession_number` (string): SEC accession number in the canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`). Globally unique across EDGAR; the natural primary key for any filing. Pass this to `GET /api/v1/sec/filings/{accession_number}` to retrieve metadata and document URLs.
- `data[].ticker` (string (nullable)): Resolved ticker from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals filing Form 4, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class (e.g. BRK-A for Berkshire Hathaway).
- `data[].form_type` (string): Canonical SEC form type as filed (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13F-NT`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Amendment variants append `/A` (e.g. `13D/A`, `10-K/A`). NT-prefixed and -NT-suffixed forms (`NT 10-K`, `13F-NT`) appear verbatim — these have no information table to drill into. Reference [SEC EDGAR form types](https://www.sec.gov/forms) for the full catalog.
- `data[].cik` (string (nullable)): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Note: SEC EDGAR's submissions API returns the unpadded form; FinRadar normalizes to 10-char padded form everywhere. Stable across decades — same CIK refers to the same legal entity.
- `data[].entity_name` (string (nullable)): Filer's legal entity name as registered with SEC (e.g. `Apple Inc.`, `BERKSHIRE HATHAWAY INC`). Casing is whatever EDGAR provides — typically uppercase for institutional filers, mixed-case for issuers. For display, prefer the `company_name` alias which is the same value.
- `data[].company_name` (string (nullable)): Frontend-friendly alias of `entity_name`. Same value, kept for backwards compatibility with older client code that queried `company_name`.
- `data[].role` (string (nullable)): Role of the filer in this filing — relevant for insider filings (Form 4) and institutional filings (13F). Null for issuer filings (10-K/10-Q/8-K). Common values: `Reporting Owner`, `Issuer`, `Filer`.
- `data[].title` (string): Free-text title from the EDGAR submissions feed (e.g. `8-K - APPLE INC (0000320193) (Filer)`). Useful for full-text search; for structured fields prefer `form_type` + `entity_name`.
- `data[].summary_html` (string (nullable)): Optional HTML summary block from EDGAR (typically empty on Form 4 and 8-K; populated on 13F-HR with structured holdings summary). Treat as untrusted HTML — sanitize before rendering in a browser.
- `data[].filing_size` (string (nullable)): Filing size as a human-readable string (e.g. `"245 KB"`, `"2.1 MB"`). NOT a numeric byte count — for byte-level work parse the string client-side or fetch the document directly.
- `data[].filed_date` (string (nullable)): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET (NOT UTC; matches the date EDGAR's index pages show). For intra-day ordering use `updated_at` which carries a full timestamp.
- `data[].filed_at` (string (nullable)): Frontend-friendly alias of `filed_date`. Same value, kept for backwards compatibility.
- `data[].updated_at` (string): ISO-8601 UTC timestamp of the last server-side update to this row (e.g. on a backfill refresh). Use as the cursor for incremental sync — sort `updated_at:desc` and persist the max value as your watermark.
- `data[].primary_link` (string (nullable)): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use this as the human-readable link in dashboards.
- `data[].primary_html_url` (string (nullable)): Direct URL of the filing's primary HTML document (the actual 10-K/8-K/13F body, not the index page). For programmatic access use this with `GET /api/v1/sec/document?url=...` or with `GET /api/v1/sec/filings/{accession_number}/html`.
- `data[].document_files` (array (nullable)): JSON array of structured document descriptors `[{type, document, description, size}, ...]` extracted from the filing's index page. Useful for filtering specific exhibits (e.g. EX-99.1, EX-10.1) before fetching.
- `data[].data_files` (array (nullable)): JSON array of XBRL/data file descriptors `[{type, document, description, size}, ...]`. Populated on 10-K/10-Q/8-K filings with embedded XBRL; null on filings without XBRL (e.g. older Form 4s).
- `data[].items` (array (nullable)): Array of 8-K item codes disclosed in this filing (e.g. `["2.02", "9.01"]` for an earnings-release 8-K). Null on non-8-K forms. Use for material-event surveillance — filter on specific item codes (1.01 = Material Definitive Agreement, 2.02 = Earnings, 5.02 = Officer Change, 8.01 = Other).
- `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end date for 10-K/10-Q, the trade date for Form 4, the report date for 13F-HR). Null for filings without a meaningful period (e.g. some 8-Ks). Differs from `filed_date` — `period_of_report` is the as-of date, `filed_date` is the disclosure date.
- `data[].sic` (string (nullable)): Standard Industrial Classification code (4-digit string, e.g. `3674` = Semiconductors). Null when not assigned. For richer industry categorization, join against the Sharadar SF1 industry table via the resolved ticker.
- `data[].all_links` (array (nullable)): Array of every document URL listed on the filing's index page — exhibits, XBRL data, images, the primary document. Pass any element to `GET /api/v1/sec/document?url=...` to fetch its content.
- `data[].first_seen_at` (string): ISO-8601 UTC timestamp when FinRadar first ingested this filing (typically within seconds of SEC acceptance for filings caught by the RSS poller; longer for backfilled rows). Use for ingest-latency analytics.
- `data[].last_seen_at` (string): ISO-8601 UTC timestamp of the last time the RSS poller observed this filing on EDGAR. Updated on every poll cycle for filings still in the active feed; frozen for older filings.
- `meta.pagination` (object): Offset-based pagination metadata: `{total, limit, offset, has_more}`. Use `has_more` as the canonical end-of-iteration signal rather than comparing `data.length` to `limit`.
- `meta.pagination.total` (integer): Exact total count of filings matching the query (full-table count, not just the current page). Computed via a parallel `COUNT(*)` query — reliable for UI pagers but adds ~50-200ms latency on broad queries.
- `meta.pagination.has_more` (boolean): `true` when more pages exist beyond this one (`total > offset + data.length`). Canonical end-of-iteration signal — when `false`, stop paginating.
- `meta.backfilled_from_edgar` (boolean (nullable)): Present and `true` ONLY when this call triggered an auto-backfill from SEC EDGAR (i.e. the ticker had no local data or only recent RSS-captured data). Absent on the typical hot-path call. Use to surface a UX hint ("first call took a moment to fetch full history").
- `meta.requested_ticker` (string (nullable)): Echo of the resolved ticker after Phase-53 normalization (e.g. `BRK.A` becomes `BRK-A`). Present only when the request included a `ticker` param.
- `meta.primary_ticker` (string (nullable)): Canonical primary share class for the filer (e.g. for Berkshire Hathaway, returns `BRK-A` even if the user queried `BRK.B`). Use to pivot to the multi-class top-of-book.
- `meta.cik` (string (nullable)): 10-char zero-padded CIK of the resolved ticker. Use as the join key against XBRL, 13F, or insider-filing tables.
- `meta.company` (string (nullable)): Resolved entity name for the ticker (e.g. `Apple Inc.`). Useful as a display label when the user queried by ticker rather than entity_name.

**Since:** v1.0.0

**Utility:** Canonical SEC filings list endpoint — paginated, ticker/CIK/form-type/date-range filterable, and self-healing (auto-backfills from SEC EDGAR's submissions API on first ticker query so you never see an empty result for a real issuer). Returns one row per filing with the SEC accession number, filer CIK + entity name + ticker, the form type (canonical strings: `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`, etc. — see [SEC EDGAR's form-type catalog](https://www.sec.gov/forms) for the full list), filing dates, and the document URL set (`primary_link`, `primary_html_url`, full `all_links` array). Pair this with `GET /api/v1/sec/filings/{accession_number}` to drill into a specific filing's documents, with `POST /api/v1/scrapping/search/` for full-text content search across filing bodies, or with `GET /api/v1/sec/filings/stats` for aggregate counts.

**Use case:** Building a timeline of filings for a specific company or monitoring all new 8-K filings. Example: GET /api/v1/sec/filings?ticker=XAIR&limit=500 returns all XAIR filings, auto-fetching from EDGAR if needed.

**Parameters:**
- `ticker` (query, optional): Company Ticker (e.g. AAPL). Triggers auto-backfill from SEC EDGAR if no local data exists.
- `form_type` (query, optional): Filter by Form Type (10-K, 4, 8-K)
- `from_date` (query, optional): Start Date (YYYY-MM-DD)
- `to_date` (query, optional): End Date (YYYY-MM-DD)
- `sort` (query, optional, default: filed_date:desc): Sort order. Format: field:direction. Fields: filed_date, updated_at. Directions: asc, desc. Shorthand 'asc'/'desc' also accepted (defaults to filed_date). Examples: sort=desc, sort=filed_date:asc
- `limit` (query, optional, default: 50): Max 500 records
- `offset` (query, optional, default: 0): Pagination offset

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": [
    {
      "id": 18234567,
      "accession_number": "0000320193-25-000123",
      "ticker": "AAPL",
      "form_type": "10-K",
      "cik": "0000320193",
      "entity_name": "Apple Inc.",
      "company_name": "Apple Inc.",
      "role": null,
      "title": "10-K - APPLE INC (0000320193) (Filer)",
      "summary_html": null,
      "filing_size": "12.4 MB",
      "filed_date": "2025-11-01",
      "filed_at": "2025-11-01",
      "updated_at": "2025-11-01T20:14:32.000Z",
      "primary_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K&dateb=&owner=include&count=40",
      "primary_html_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "document_files": [
        {
          "type": "10-K",
          "document": "aapl-20250928.htm",
          "description": "10-K",
          "size": "12943821"
        }
      ],
      "data_files": [
        {
          "type": "EX-101.INS",
          "document": "aapl-20250928.xml",
          "description": "XBRL Instance Document",
          "size": "412390"
        }
      ],
      "items": null,
      "period_of_report": "2025-09-28",
      "sic": "3571",
      "all_links": [
        "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
        "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml"
      ],
      "first_seen_at": "2025-11-01T20:14:35.000Z",
      "last_seen_at": "2025-11-02T03:00:01.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2148,
      "limit": 50,
      "offset": 0,
      "has_more": true
    },
    "requested_ticker": "AAPL",
    "primary_ticker": "AAPL",
    "cik": "0000320193",
    "company": "Apple Inc."
  }
}
```

### POST /api/v1/sec/filings/backfill

Explicitly backfill ALL historical filings for a ticker from SEC EDGAR. Fetches the complete filing history from data.sec.gov/submissions/ and stores it locally. Subsequent GET queries will return the full history instantly.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`).
- `data` (object): Backfill result envelope — see `data.*` for fields. Wall-clock duration scales with how many filings the issuer has — typically 2-15s for an issuer with 500-3000 historical filings; longer for very-tenured issuers (e.g. GE, IBM) which can have 10K+ filings.
- `data.ticker` (string): Echoed input ticker after Phase-53 normalization (e.g. `BRK.A` → `BRK-A`). Useful for confirming the resolution before relying on it downstream.
- `data.cik` (string): 10-char zero-padded CIK resolved from the input ticker. Use this as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.
- `data.company` (string): Resolved entity name (e.g. `Apple Inc.`). Useful as a display label for the backfilled batch.
- `data.inserted` (integer): Count of NEW filings inserted into the local index by this call (rows that didn't exist before). 0 on a no-op repeat call. Compare against `total_from_edgar` to gauge completeness.
- `data.already_existed` (integer): Count of EDGAR filings that were already in the local index (skipped via the `(accession_number, cik)` UNIQUE constraint). On a fresh-ticker backfill: 0. On a repeat call: equals `total_from_edgar`.
- `data.total_from_edgar` (integer): Total count of filings returned by SEC EDGAR's submissions API for this CIK. Equals `inserted + already_existed + errors`.
- `data.errors` (integer): Count of EDGAR rows that failed to ingest (parse errors, transient DB issues). Should typically be 0 — non-zero values indicate a parse-edge-case worth filing a support ticket for. Errors are logged server-side with the accession number.

**Since:** v1.0.0

**Utility:** Explicit, free (cost: 0) trigger to pre-load the FULL submissions history for a ticker from SEC EDGAR's `data.sec.gov/submissions/CIK{cik}.json` endpoint into FinRadar's local index. Use this to warm the cache before running an analysis batch — once a ticker has been backfilled, every subsequent call to `GET /api/v1/sec/filings?ticker=X` hits the local DB instantly (no SEC round-trip). Cost is zero because the work is one-shot per-ticker — repeated backfills detect the existing rows via the `(accession_number, cik)` UNIQUE constraint and only insert deltas. Idempotent: safe to call multiple times — `inserted` will be 0 on no-op repeat calls.

**Use case:** Call POST /filings/backfill?ticker=AAPL to load all ~2000 Apple filings in one shot, then query them instantly with GET /filings?ticker=AAPL.

**Parameters:**
- `ticker` (query, required): Stock ticker to backfill (e.g. XAIR, AAPL, TSLA)

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "ticker": "AAPL",
    "cik": "0000320193",
    "company": "Apple Inc.",
    "inserted": 1843,
    "already_existed": 0,
    "total_from_edgar": 1843,
    "errors": 0
  }
}
```

### GET /api/v1/sec/filings/{accession_number}

Get filing metadata by accession number — returns filing details, document URLs (all_links), and structured data. Does NOT return the document content itself.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`).
- `data` (object): Full filing metadata record. Same shape as a single element of `GET /api/v1/sec/filings`'s `data[]` array, PLUS the `raw_entry_xml` field (which is excluded from list responses for payload-size reasons). See `data.*` for fields.
- `data.id` (integer): Internal `sec_filing_entries.id` row ID (auto-increment primary key).
- `data.accession_number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. Echoes the input.
- `data.ticker` (string (nullable)): Resolved ticker from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker.
- `data.form_type` (string): Canonical SEC form type as filed (e.g. `10-K`, `13F-HR`, `8-K`, `4`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Amendment variants append `/A`. NT-prefixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim. Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `data.cik` (string (nullable)): Filer CIK as a zero-padded 10-character string (e.g. `0000320193`).
- `data.entity_name` (string (nullable)): Filer's legal entity name as registered with SEC.
- `data.company_name` (string (nullable)): Frontend-friendly alias of `entity_name`.
- `data.role` (string (nullable)): Role of the filer in this filing (`Reporting Owner`, `Issuer`, `Filer`). Null for issuer filings.
- `data.title` (string): Free-text title from the EDGAR submissions feed.
- `data.summary_html` (string (nullable)): Optional HTML summary block from EDGAR. Sanitize before rendering.
- `data.filing_size` (string (nullable)): Filing size as a human-readable string (e.g. `"245 KB"`, `"2.1 MB"`). NOT a numeric byte count.
- `data.filed_date` (string (nullable)): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET.
- `data.filed_at` (string (nullable)): Frontend-friendly alias of `filed_date`.
- `data.updated_at` (string): ISO-8601 UTC timestamp of the last server-side update to this row.
- `data.primary_link` (string (nullable)): Canonical SEC EDGAR URL for the filing's index page.
- `data.primary_html_url` (string (nullable)): Direct URL of the filing's primary HTML document (the actual 10-K/8-K/13F body). For the parsed body content use the `/html` companion endpoint.
- `data.document_files` (array (nullable)): JSON array of structured document descriptors `[{type, document, description, size}, ...]`.
- `data.data_files` (array (nullable)): JSON array of XBRL/data file descriptors `[{type, document, description, size}, ...]`. Populated on filings with embedded XBRL.
- `data.items` (array (nullable)): Array of 8-K item codes disclosed in this filing (e.g. `["2.02", "9.01"]`). Null on non-8-K forms.
- `data.period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (fiscal-period-end for 10-K/10-Q, trade date for Form 4, report date for 13F-HR).
- `data.sic` (string (nullable)): Standard Industrial Classification code (4-digit string).
- `data.all_links` (array (nullable)): Array of every document URL listed on the filing's index page — exhibits, XBRL data, images, the primary document. Pass any element to `GET /api/v1/sec/document?url=...` to fetch its content.
- `data.raw_entry_xml` (string (nullable)): Raw XML entry from SEC EDGAR's RSS feed at the time of ingestion. Useful for forensic / audit-trail work — preserved verbatim from EDGAR for filings ingested via the RSS poller. Null for filings ingested via the submissions-API backfill path (which doesn't expose entry XML). NOT returned by the list endpoint — only the detail endpoint includes this field.
- `data.first_seen_at` (string): ISO-8601 UTC timestamp when FinRadar first ingested this filing.
- `data.last_seen_at` (string): ISO-8601 UTC timestamp of the last time the RSS poller observed this filing on EDGAR.

**Since:** v1.0.0

**Utility:** Canonical filing-detail lookup by SEC accession number — returns the full metadata record (form type, filer CIK + entity name, filed date, period of report, SIC, summary HTML, the complete `all_links` array of every document URL in the filing package, and the `raw_entry_xml` from EDGAR's RSS feed for archival/audit). The natural "step 1" of any filing workflow: find the filing by some other route (search, RSS, ticker timeline), then call this to get the document URLs, then drill into a specific document via `/{accession_number}/html` (primary doc shortcut) or `/api/v1/sec/document?url=...` (any document by URL). Accession numbers are 18-char dashed `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`); the path-parameter accepts either the dashed or the un-dashed form.

**Use case:** You have an accession number (e.g. from a search) and need the filing date, form type, filer info, and links to all documents in the filing package.

**Parameters:**
- `accession_number` (path, required): SEC accession number in 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`). Also accepts the un-dashed 18-char form (`000032019325000123`). Returns 404 when the accession is not in the local index — call `POST /api/v1/sec/filings/backfill?ticker=...` first if you suspect the ticker hasn't been backfilled yet.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "id": 18234567,
    "accession_number": "0000320193-25-000123",
    "ticker": "AAPL",
    "form_type": "10-K",
    "cik": "0000320193",
    "entity_name": "Apple Inc.",
    "company_name": "Apple Inc.",
    "role": null,
    "title": "10-K - APPLE INC (0000320193) (Filer)",
    "summary_html": null,
    "filing_size": "12.4 MB",
    "filed_date": "2025-11-01",
    "filed_at": "2025-11-01",
    "updated_at": "2025-11-01T20:14:32.000Z",
    "primary_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K",
    "primary_html_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
    "document_files": [
      {
        "type": "10-K",
        "document": "aapl-20250928.htm",
        "description": "10-K",
        "size": "12943821"
      }
    ],
    "data_files": [
      {
        "type": "EX-101.INS",
        "document": "aapl-20250928.xml",
        "description": "XBRL Instance Document",
        "size": "412390"
      }
    ],
    "items": null,
    "period_of_report": "2025-09-28",
    "sic": "3571",
    "all_links": [
      "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml"
    ],
    "raw_entry_xml": "<entry>\n  <title>10-K - APPLE INC...</title>\n  <link href=\"https://www.sec.gov/...\" />\n  ...\n</entry>",
    "first_seen_at": "2025-11-01T20:14:35.000Z",
    "last_seen_at": "2025-11-02T03:00:01.000Z"
  }
}
```

### GET /api/v1/sec/filings/{accession_number}/html

Get the primary document's HTML content by accession number. Returns the full raw HTML of the main filing document (e.g. the 10-K, 8-K body, or — for `13F-HR` / `13F-HR/A` — the INFORMATION TABLE with positions, not the cover page). For XBRL filings, automatically resolves through the SEC viewer to the actual inline XBRL document.

**Token cost:** 5 tokens per call

**Response fields:**
- `(body)` (string): Raw filing HTML — UTF-8 encoded `text/html` body. NOT a JSON envelope (this endpoint returns the document body directly). Server-side post-processing strips `<noscript>` blocks (the SEC "Javascript required" warning) and rewrites relative `href`/`src` URLs to absolute `https://www.sec.gov/...` — so the HTML can be rendered in a browser outside sec.gov without broken assets. Length ranges from 50 KB (Form 4) to 2 MB+ (large 10-K filings).
- `(headers).Content-Type` (string): Always `text/html`. Distinguishes this endpoint from JSON-returning siblings — your client must accept HTML responses, not assume JSON.

**Since:** v1.0.0

**Utility:** One-call shortcut to the filing's PRIMARY document body — the actual 10-K / 10-Q / 8-K / 13F-HR HTML, not the index page. Auto-resolves through SEC's `/ix?doc=` inline-XBRL viewer wrapper to the underlying tagged HTML so customers don't have to handle the redirect themselves. Critical for: feeding a 10-K straight into an LLM context window without scraping EDGAR yourself, rendering filings in an embedded iframe in your dashboard, building diff tools that compare 10-K filings year-over-year. Returns `Content-Type: text/html` — NOT a JSON response (one of the few non-JSON endpoints in the surface). Pair with [`GET /api/v1/sec/document?url=...`](/docs/sec-filings/sec-filings-api/get-sec-document) when you need a specific exhibit or data file rather than the primary doc.

**Use case:** Feed a 10-K annual report or 8-K directly into an LLM context window for summarization, without needing to scrape SEC EDGAR yourself.

**Parameters:**
- `accession_number` (path, required): SEC accession number in 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. Returns 404 with a JSON error body when the accession is not in the local index (or has no extractable HTML — e.g. some pre-2001 filings are TXT-only).
- `offset` (query, optional, default: 0): Byte offset (UTF-8) at which to start the returned slice. Combine with `length`/`max_bytes` to page through a large document instead of pulling it whole. Omit (with no `length`/`max_bytes`) to get the full document — the default, unchanged behaviour.
- `length` (query, optional): Max number of UTF-8 bytes to return starting at `offset`. Alias of `max_bytes` (if both are given the smaller wins). A raw 10-K can be tens of MB; agents should bound the response (e.g. 200000) and page via `offset` to avoid context/token blow-up. When the response is sliced, truncation is reported in the response HEADERS (`X-Content-Total-Bytes`, `X-Content-Offset`, `X-Content-Returned-Bytes`, `X-Content-Truncated`) — the body stays valid HTML.
- `max_bytes` (query, optional): Alias of `length` — max UTF-8 bytes to return from `offset`. Provided for clients that think in terms of a hard response-size cap.

**Sample response:**
```json
"<html>\n<head>\n  <title>Apple Inc. 10-K (Fiscal 2025)</title>\n</head>\n<body>\n  <h1>UNITED STATES SECURITIES AND EXCHANGE COMMISSION</h1>\n  <h2>FORM 10-K</h2>\n  <p>Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934</p>\n  <p>For the fiscal year ended September 28, 2025</p>\n  ...\n  <h2>PART I — Item 1. Business</h2>\n  <p>The Company designs, manufactures and markets smartphones, personal computers, tablets...</p>\n  ...\n</body>\n</html>"
```

### GET /api/v1/sec/document?url={sec_url}

Fetch any SEC EDGAR document by its full URL. Works with any file type — HTML exhibits, XML, XBRL, images, PDFs, etc. Use this when you need a specific document (not the primary one) from a filing's document list.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx in JSON-wrapped mode. ApiResponse envelope marker. NOT present when `raw=true` (raw mode returns the document body directly, no JSON envelope).
- `request_id` (string (nullable)): Per-request UUID generated server-side. JSON-wrapped mode only.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated. JSON-wrapped mode only.
- `data` (object): Document content envelope (JSON-wrapped mode only — see `data.*`). Absent in raw mode (`?raw=true`).
- `data.url` (string): Echoed (and `/ix?doc=`-stripped) URL of the document fetched. May differ from the input URL when SEC's viewer wrapper was present.
- `data.original_url` (string (nullable)): Original URL as passed by the caller, ONLY present when the server stripped a `/ix?doc=` wrapper. Null when no rewrite occurred.
- `data.content_type` (string): Detected MIME type based on URL extension: `text/html` (.htm, .html), `application/xml` (.xml, .xsd), `application/json` (.json), `text/plain` (.txt), `image/jpeg` / `image/png` / `image/gif` / `application/pdf` (binary types), `application/octet-stream` (unknown extensions). Use to dispatch the correct decoder client-side.
- `data.size` (integer): Decoded content size in bytes. For text content this is the UTF-8 byte length; for binary content this is the post-base64-decode byte length (the actual file size, not the inflated base64-string length).
- `data.encoding` (string): `utf-8` for text content (`text/*`, `application/xml`, `application/json`) — `data.content` is decoded text. `base64` for binary content (PDFs, images) — `data.content` is base64-encoded; decode client-side before consuming.
- `data.content` (string): Document content. UTF-8 plain text for text content types; base64-encoded string for binary types (decode via `Buffer.from(content, 'base64')` in Node, `atob(content)` in browsers, or `base64.b64decode(content)` in Python). HTML content is post-processed: `<noscript>` blocks stripped, relative `href`/`src` URLs rewritten to absolute `https://www.sec.gov/...` so embedded rendering works outside sec.gov.
- `(raw mode body)` (string): When `?raw=true`: the document body is returned directly with the original `Content-Type` header (no JSON envelope). For binary types (PDFs, images), the body is the raw bytes. For HTML, the body is the post-processed UTF-8 HTML. Use raw mode for `<iframe src=...>` or `<img src=...>` embedding patterns.

**Since:** v1.0.0

**Utility:** Universal SEC EDGAR document fetcher — pass any document URL from a filing's `all_links` array (HTML exhibits, XML data files, raw XBRL instances, images, PDFs, plain-text filings) and receive the content back in either a JSON envelope (default — base64 for binary, UTF-8 for text) or a raw passthrough (`?raw=true`, sets the original `Content-Type` for iframe/img embedding). The server-side guard rejects any URL whose hostname is not in `{www.sec.gov, sec.gov, efts.sec.gov, edgar.sec.gov}` — pass-through is gated to SEC domains only. Auto-strips SEC's `/ix?doc=` inline-XBRL viewer wrapper, so passing a URL copied directly from a browser's address bar (which often has `/ix?doc=` prepended) works without manual cleanup. HTML responses get the same `_fix_sec_html` post-processing as `/{accession_number}/html` (noscript stripped, relative URLs absolutized).

**Use case:** Chain: GET /filings/{accession} → pick a URL from all_links → GET /document?url={url}. Example: fetch an exhibit agreement or an XBRL data file from a 10-K filing package.

**Parameters:**
- `url` (query, required): Full SEC EDGAR document URL — must be on `sec.gov`, `www.sec.gov`, `efts.sec.gov`, or `edgar.sec.gov`. Returns 400 BAD_REQUEST when the hostname is anything else. Get these URLs from the `all_links` array in `GET /api/v1/sec/filings/{accession_number}`'s response. The `/ix?doc=` inline-XBRL viewer wrapper is auto-stripped — pass either form.
- `raw` (query, optional, default: false): If `true`, returns raw content with the original `Content-Type` header (for iframe rendering or direct binary download). If `false` or omitted, returns a JSON envelope with content in `data.content` (UTF-8 for text, base64 for binary). For LLM ingestion of HTML/XML use the default JSON mode; for `<iframe>` or `<img>` embedding use `raw=true`.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
    "original_url": null,
    "content_type": "text/html",
    "size": 12943821,
    "encoding": "utf-8",
    "content": "<html>\n<head><title>Apple Inc. Form 10-K</title></head>\n<body>\n<h1>UNITED STATES SECURITIES AND EXCHANGE COMMISSION</h1>\n<h2>FORM 10-K</h2>\n<p>Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934. For the fiscal year ended September 28, 2025.</p>\n<h2>PART I — Item 1. Business</h2>\n<p>The Company designs, manufactures and markets smartphones, personal computers, tablets, wearables and accessories...</p>\n..."
  }
}
```

### GET /api/v1/sec/forms

List all supported form types with descriptions. Each entry includes form_type, root_form_type, a human-readable description (covers all 352 root types), filing_count, first_filed, and last_filed. Amendment variants (/A) auto-append '(Amendment)' to the root type's description.

**Token cost:** 1 token per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (array): Array of form-type entries sorted by `filing_count DESC` (most-common forms first). Up to `limit` entries (default 500). One entry per distinct `form_type` — see `data[].*` for shape.
- `data[].form_type` (string): Canonical SEC form type as it appears in filings (e.g. `4`, `13F-HR`, `8-K`, `10-K`, `10-Q`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`, `13F-HR/A`). Amendment variants append `/A`. NT-prefixed forms (`NT 10-K`, `13F-NT`) appear verbatim.
- `data[].root_form_type` (string): Form type with the `/A` amendment suffix stripped (e.g. `13D/A` → `13D`, `10-K/A` → `10-K`). Useful for grouping amendments alongside their original-filing siblings (`SELECT * FROM forms WHERE root_form_type = '13D'`). For non-amendment forms, this equals `form_type`.
- `data[].description` (string): Human-readable description of the form's purpose (e.g. for `4` = "Statement of Changes in Beneficial Ownership", for `13F-HR` = "Information Required of Institutional Investment Managers Form 13F", for `S-1` = "Registration Statement under the Securities Act of 1933"). Covers all 352 SEC root form types. For amendments, the suffix " (Amendment)" is auto-appended.
- `data[].filing_count` (integer): Count of filings of this exact `form_type` in the local index. Reflects ingest coverage, not SEC's universe — recently-onboarded form types may show low counts here even though they're widely filed.
- `data[].first_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the EARLIEST filing of this type in the local index. Null when no filings have a `filed_date` (rare). Useful for spotting newly-introduced form types (e.g. `2026-` indicates a form added recently).
- `data[].last_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the MOST RECENT filing of this type in the local index. Null when no filings have a `filed_date`. Forms that haven't been filed in years (e.g. `last_filed: '2018-...'`) suggest deprecated form types — useful for hiding legacy types from active dropdowns.

**Since:** v1.0.0

**Utility:** Cheap (1 token) form-type catalog endpoint — returns every distinct form type observed in the local filings index alongside human-readable descriptions, filing counts, and the first/last dates each form type appears in the index. The single source of truth for: form-type dropdown menus in search UIs, tooltips that explain `13F-NT` vs `13F-HR`, autocomplete chips showing "how many of these have we seen" counts. Descriptions cover all 352 SEC root form types ([catalog](https://www.sec.gov/forms)) — amendment variants (`/A` suffix) auto-append "(Amendment)" to the description (e.g. `13D/A` description = "Statement of Beneficial Ownership (Amendment)"). Sorted by `filing_count DESC` so the most common forms (4, 13F-HR, 8-K, 10-K, 10-Q, S-1) surface first.

**Use case:** Populating a dropdown menu or table for 'Form Type' selection in a search UI, with descriptions so users understand each form type without looking it up.

**Parameters:**
- `q` (query, optional): Search form types by name — case-insensitive substring match against `form_type`. E.g. `q=13F` returns `13F-HR`, `13F-NT`, `13F-HR/A`. Use to narrow large lists; omit for full catalog.
- `limit` (query, optional, default: 500): Max results — clamped server-side to range `[1, 1000]`. Use 500 (default) for full catalog dropdowns; lower (10-20) for autocomplete-style hints.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": [
    {
      "form_type": "4",
      "root_form_type": "4",
      "description": "Statement of Changes in Beneficial Ownership",
      "filing_count": 8240194,
      "first_filed": "2002-08-29",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "13F-HR",
      "root_form_type": "13F-HR",
      "description": "Information Required of Institutional Investment Managers Form 13F",
      "filing_count": 384529,
      "first_filed": "2003-02-14",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "8-K",
      "root_form_type": "8-K",
      "description": "Current report",
      "filing_count": 1294831,
      "first_filed": "1996-03-15",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "10-K",
      "root_form_type": "10-K",
      "description": "Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934",
      "filing_count": 248194,
      "first_filed": "1993-08-30",
      "last_filed": "2026-05-01"
    }
  ]
}
```

### GET /api/v1/sec/entities

Return unique entity names, optionally filtered by filing form type. Results are alphabetically sorted and cached for 5 minutes.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. Note: this endpoint uses a custom `jsonify` envelope rather than `ApiResponse.success()` to control the `Cache-Control` header — so `request_id` and `timestamp` are NOT present (unlike sibling endpoints in this section).
- `data` (array): Array of distinct entity records, sorted alphabetically by `entity_name` (case-sensitive — uppercase names sort before lowercase per default Postgres collation). One entry per unique `(entity_name, cik)` pair. Empty array when no filings match the filter — never null.
- `data[].entity_name` (string): Filer's legal entity name as registered with SEC. Casing reflects EDGAR's stored form — typically uppercase for institutional filers (e.g. `BERKSHIRE HATHAWAY INC`, `BLACKROCK INC`), mixed-case for issuers (e.g. `Apple Inc.`, `Microsoft Corporation`). The same legal entity can appear with multiple cosmetic variants if EDGAR registrants update their formal name — dedupe client-side via `cik` if needed.
- `data[].cik` (string): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Stable across decades — same CIK refers to the same legal entity even if `entity_name` cosmetic variations exist. Use as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.

**Since:** v1.0.0

**Utility:** Distinct-entity catalog endpoint — returns every unique `(entity_name, cik)` pair observed in the local filings index, alphabetically sorted, optionally filtered by form type. The right surface for: form-type-aware autocomplete ("only show entities that have actually filed a 10-K"), notification-rule builders (user picks form type → entity search shows only relevant filers), entity-pivot navigation in the SEC workstation. Server-side `Cache-Control: public, max-age=300` (5 min cache) — entity list mutates slowly so caching is safe; expect a 5-minute lag for newly-onboarded filers. Returns a non-standard envelope (`{status, data}` only — NO `request_id` or `timestamp`) because the handler builds its own `jsonify` for cache-header control rather than going through `ApiResponse.success()`.

**Use case:** In notification settings, user selects a form type (e.g. 10-K), then a search bar appears where they can search for specific entities to watch. The autocomplete only shows entities that actually have filings of the selected form type. Also used in the SEC workstation for general entity search by company name.

**Parameters:**
- `form_type` (query, optional): Filter to entities with filings of this type (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). If omitted, returns all entities across all form types. Case-sensitive — pass exactly as it appears in `data[].form_type` from `GET /api/v1/sec/forms`.

**Sample response:**
```json
{
  "status": "success",
  "data": [
    {
      "entity_name": "ABBVIE INC.",
      "cik": "0001551152"
    },
    {
      "entity_name": "Apple Inc.",
      "cik": "0000320193"
    },
    {
      "entity_name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983"
    },
    {
      "entity_name": "BlackRock, Inc.",
      "cik": "0001364742"
    },
    {
      "entity_name": "Microsoft Corporation",
      "cik": "0000789019"
    }
  ]
}
```

### GET /api/v1/filings

Generic filings list — alias of /api/v1/sec/filings without the /sec prefix. Same query semantics; returns the same filings array.

**Token cost:** 10 tokens per call

**Response fields:**
- `filings` (array): Array of filing rows matching the query, sorted by `filed_date DESC` by default (newest first). Empty array when no rows match — never null. Pagination is cursor-based; consult `pagination.next_cursor` rather than `filings.length` to detect the last page.
- `filings[].accession_number` (string): SEC accession number in the canonical `XXXXXXXXXX-YY-NNNNNN` format (e.g. `0001127602-26-001234`). Globally unique across EDGAR; the natural primary key for any filing. Pass this to `GET /api/v1/sec/filings/{accession_number}` to retrieve metadata and document URLs.
- `filings[].cik` (string): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Note: SEC EDGAR's submissions API returns the unpadded form; FinRadar normalizes to 10-char padded form everywhere except the URL path parameters that explicitly accept either.
- `filings[].ticker` (string (nullable)): Ticker symbol resolved from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs, dissolved entities). Primary-share-class is preferred when a filer has multiple tickers (e.g. BRK-A is returned for Berkshire Hathaway).
- `filings[].form_type` (string): Canonical SEC form type as filed (e.g. `4`, `13F-HR`, `8-K`, `10-K`, `10-Q`, `S-1`, `20-F`). Amendment variants append `/A` (e.g. `13D/A`). NT-prefixed and -NT-suffixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim — these have no information table to drill into.
- `filings[].filed_date` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET (NOT UTC; matches the date EDGAR's index pages show). For intra-day ordering use the parent filing's full timestamp via `GET /api/v1/sec/filings/{accession_number}`.
- `filings[].filing_url` (string): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use this as the human-readable link in dashboards; for programmatic document access use the `/html` or `/document` companion endpoints which return parsed content.
- `pagination` (object): Cursor-based pagination metadata. Cursor pagination (vs offset) is stable under concurrent inserts — no risk of skipping or double-counting filings as new ones land mid-iteration.
- `pagination.next_cursor` (string (nullable)): Opaque base64-encoded cursor for the next page. Pass this verbatim as the `cursor` query parameter on the next call. Null when there are no further pages — that is the canonical end-of-iteration signal.
- `pagination.total` (integer): Exact total count of filings matching the query (full-table count, not just the current page). Computed via a parallel `COUNT(*)` query — reliable for UI pagers but adds ~50-200ms latency on broad queries; pass `count=false` (when supported) to skip it for cursor-only iteration.

**Since:** v1.0.0

**Utility:** List EDGAR filings across all 350+ form types with pagination, ticker/CIK filtering, date ranges, and form-type filters — the canonical entry point for any analyst, screening pipeline, or dashboard that needs a chronological view of SEC filings. Identical query shape and cost to `/api/v1/sec/filings`; this path exists so legacy tooling that omits the `/sec/` namespace continues to work. Pair this with `GET /api/v1/sec/filings/{accession_number}` to drill into a specific filing's documents, or with `POST /api/v1/scrapping/search/` for full-text content search across filing bodies.

**Sample response:**
```json
{
  "filings": [
    {
      "accession_number": "0001127602-26-001234",
      "cik": "0000320193",
      "ticker": "AAPL",
      "form_type": "4",
      "filed_date": "2026-04-15",
      "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6...",
    "total": 12480
  }
}
```

### GET /api/v1/sec/filings/stats

Aggregate counts of filings by form type, filer, or date range. Returns counts only — does not return individual filings.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (object): Stats envelope — see `data.*` for fields. All counts reflect the local index, not SEC's universe (recently-onboarded form types may show low counts here even though they're widely filed).
- `data.total_entries` (integer): Total count of filings in the local `sec_filing_entries` index (all form types, all filers, all dates). Computed via `COUNT(*)` — typically 30M+ rows in the production index.
- `data.top_form_types` (array): Top 10 form types by `filing_count`, sorted descending. Always 10 elements (or fewer if the index has fewer distinct form types — extremely unlikely in production). Mirrors the top of `GET /api/v1/sec/forms`'s response.
- `data.top_form_types[].form_type` (string): Canonical SEC form type (e.g. `4`, `13F-HR`, `8-K`).
- `data.top_form_types[].count` (integer): Filing count for this form type. Typically dominated by Form 4 (insider transactions, ~8M+) and 13F-HR (institutional holdings, ~400K).
- `data.latest_filing_date` (string (nullable)): ISO date `YYYY-MM-DD` of the most recent filing in the local index (`MAX(filed_date)`). Use as the freshness canary — should never be more than 1-2 days behind today during active business hours; gaps suggest the RSS poller is stalled. Null only when the index is empty (initial setup).
- `data.timestamp` (string): ISO-8601 UTC timestamp the stats query ran server-side. Inside `data` rather than the envelope's `timestamp` — useful for stats-snapshot caching.

**Since:** v1.0.0

**Utility:** Aggregate-counts endpoint over the local filings index — total filing count, top-10 form types by count, latest filing date observed. The right surface for: dashboard headline stats ("X filings indexed; latest 2026-05-02"), monitoring panels checking ingest freshness (`latest_filing_date` should never be more than 1-2 days behind today during active hours), the "Did our RSS poller break?" canary. Returns aggregates only — no per-filing rows. For filtered counts (e.g. "how many 8-Ks did Apple file in 2025?") combine `GET /api/v1/sec/filings?ticker=...&form_type=...&from_date=...` with a `count`-only query against the `meta.pagination.total` field.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "total_entries": 32184529,
    "top_form_types": [
      {
        "form_type": "4",
        "count": 8240194
      },
      {
        "form_type": "13F-HR",
        "count": 384529
      },
      {
        "form_type": "8-K",
        "count": 1294831
      },
      {
        "form_type": "10-Q",
        "count": 412938
      },
      {
        "form_type": "10-K",
        "count": 248194
      },
      {
        "form_type": "S-1",
        "count": 184201
      },
      {
        "form_type": "DEF 14A",
        "count": 132481
      },
      {
        "form_type": "13D",
        "count": 98412
      },
      {
        "form_type": "13G",
        "count": 84592
      },
      {
        "form_type": "144",
        "count": 78201
      }
    ],
    "latest_filing_date": "2026-05-02",
    "timestamp": "2026-05-02T16:30:14.122000"
  }
}
```

### GET /api/v1/sec/forms/{form_type}

Get details for a specific SEC form type. Returns the form's metadata (description, filing count, first/last filed dates) — same shape as one element of GET /api/v1/sec/forms.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (object): Form-type detail record. Same shape as one element of `GET /api/v1/sec/forms`'s `data[]` array.
- `data.form_type` (string): Canonical form type as resolved (case-corrected from input — e.g. requesting `13f-hr` returns `13F-HR`). Echoes the canonical-cased form.
- `data.root_form_type` (string): Form type with `/A` amendment suffix stripped. For non-amendments, equals `form_type`.
- `data.description` (string): Human-readable description of the form's purpose (e.g. for `13F-HR` = "Information Required of Institutional Investment Managers Form 13F", for `10-K` = "Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934"). Covers all 352 SEC root form types. For amendments, suffixed with " (Amendment)". Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `data.filing_count` (integer): Count of filings of this exact `form_type` in the local index. Reflects ingest coverage, not SEC's universe.
- `data.first_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the EARLIEST filing of this type in the local index. Null only when no filings have a `filed_date` (rare).
- `data.last_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the MOST RECENT filing of this type in the local index. Useful for deprecation detection — `last_filed` more than a year ago suggests the form may be retired.

**Since:** v1.0.0

**Utility:** Single-form-type detail lookup — pass a form type via the path (e.g. `/api/v1/sec/forms/13F-HR`) and receive its metadata: human-readable description, total filing count in the local index, first/last dates seen. Path-parameter variant of asking the catalog endpoint for a specific row. The right call for: form-type-specific landing pages ("All you need to know about Form 13F-HR"), tooltip enrichment when you have a form type but no description, deprecation detection (compare `last_filed` against current date — gaps > 1 year suggest the form has been retired). Two-stage CIK-insensitive lookup: tries exact-match `form_type` first, falls back to case-insensitive `ILIKE` if no rows match.

**Use case:** User clicks a form-type chip in the docs UI → land on a form-type page → pull description + filing count + date range to populate the page header.

**Parameters:**
- `form_type` (path, required): Canonical SEC form type (e.g. `10-K`, `13F-HR`, `8-K`, `4`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Case-insensitive — server tries exact match first, falls back to `ILIKE`. Amendment variants (`10-K/A`, `13D/A`) work — pass them verbatim. Returns 404 NOT_FOUND when no filings of this type exist in the local index.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "form_type": "13F-HR",
    "root_form_type": "13F-HR",
    "description": "Information Required of Institutional Investment Managers Form 13F",
    "filing_count": 384529,
    "first_filed": "2003-02-14",
    "last_filed": "2026-05-02"
  }
}
```