{"schema_version":"v1","frozen_on":"2026-07-23","stability":"v1 fields never change meaning or type. Evolution is additive only (new fields, new object types). Anything breaking requires a v2 namespace and a deprecation window.","design_rules":["Values are strings exactly as filed — share counts, prices, and dates are never coerced to numbers or dates. Consumers coerce at their edge.","Absent means null, never missing — every documented field is always present; null means 'not stated in the filing', empty lists/objects mean 'none'.","The SEC accession number is the unique, stable identity of every filing."],"list_envelope":{"description":"Shape of every list endpoint response.","fields":{"data":{"type":"array[object]","description":"Page of schema objects."},"total":{"type":"integer","description":"Total rows matching the filters."},"limit":{"type":"integer","description":"Page size used (max 200)."},"offset":{"type":"integer","description":"Offset used (max 10,000)."}}},"objects":{"form4":{"description":"One Form 4 / 4/A insider-transaction filing, normalized from the ownership XML. Returned by /v1/insider-trades.","fields":{"accession":{"type":"string","description":"SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe and to fetch /v1/insider-trades/{accession}. Merged at the API layer; added 2026-08-08."},"filed_date":{"type":"string|null","description":"Date EDGAR accepted the filing, normalized to YYYY-MM-DD from the feed timestamp — the value since= filters and list ordering use. A computed convenience field (a deliberate, clearly-marked exception to the as-filed rule). Merged at the API layer; added 2026-08-08."},"form_type":{"type":"string","description":"\"4\" or \"4/A\" as filed."},"period":{"type":"string|null","description":"Period of report, YYYY-MM-DD as filed."},"amendment_date":{"type":"string|null","description":"On 4/A only: date of the original submission being amended; null on originals."},"issuer":{"type":"object","description":"{name, cik, ticker} — all string|null, as filed."},"reporting_owners":{"type":"array[object]","description":"One reporting_owner per insider on the filing (multi-owner filings are common for funds)."},"transactions":{"type":"array[object]","description":"All transaction rows, non-derivative first, then derivative."},"holdings":{"type":"array[object]","description":"Position statements with no transaction (holdings-only and mixed filings)."},"footnotes":{"type":"object","description":"Footnote text keyed by id, e.g. {\"F1\": \"...\"}; whitespace-normalized."},"remarks":{"type":"string|null","description":"Free-text remarks field."},"holdings_only":{"type":"boolean","description":"true when the filing reports no transactions."},"source_url":{"type":"string","description":"EDGAR URL of the ownership XML this was normalized from."},"normalized_by":{"type":"string","description":"Parser version stamp."}}},"form4.reporting_owner":{"description":"One insider on a Form 4.","fields":{"name":{"type":"string|null","description":"As filed (EDGAR convention is often LAST FIRST)."},"cik":{"type":"string|null","description":"Owner CIK, zero-padded as filed."},"is_director":{"type":"string|null","description":"Filed as \"1\"/\"0\"/\"true\"/\"false\" — passed through as filed."},"is_officer":{"type":"string|null","description":"As filed (see is_director)."},"is_ten_pct_owner":{"type":"string|null","description":"As filed (see is_director)."},"officer_title":{"type":"string|null","description":"e.g. \"Chief Executive Officer\"."}}},"form4.transaction":{"description":"One transaction row (non-derivative or derivative table).","fields":{"security_title":{"type":"string|null","description":"e.g. \"Class A Common Stock\"."},"transaction_date":{"type":"string|null","description":"YYYY-MM-DD as filed."},"transaction_code":{"type":"string|null","description":"SEC transaction code — see transaction_codes."},"acquired_disposed":{"type":"string|null","description":"\"A\" acquired / \"D\" disposed."},"shares":{"type":"string|null","description":"Share/unit count as filed."},"price_per_share":{"type":"string|null","description":"As filed; null is common on grants/awards."},"shares_owned_after":{"type":"string|null","description":"Post-transaction holdings."},"ownership_type":{"type":"string|null","description":"\"D\" direct / \"I\" indirect."},"is_derivative":{"type":"boolean","description":"true for derivative-table rows."},"conversion_or_exercise_price":{"type":"string|null","description":"Derivative rows; null on non-derivative."},"exercise_date":{"type":"string|null","description":"Derivative rows."},"expiration_date":{"type":"string|null","description":"Derivative rows."},"underlying_security_title":{"type":"string|null","description":"Derivative rows."},"underlying_security_shares":{"type":"string|null","description":"Derivative rows."},"footnote_ids":{"type":"array[string]","description":"Footnote ids referenced anywhere in this row; resolve via top-level footnotes."}}},"form4.holding":{"description":"One holdings row (position statement without a transaction).","fields":{"security_title":{"type":"string|null","description":"As filed."},"shares_owned":{"type":"string|null","description":"As filed."},"ownership_type":{"type":"string|null","description":"\"D\" direct / \"I\" indirect."},"nature_of_ownership":{"type":"string|null","description":"e.g. \"By Trust\" — usually paired with indirect."},"is_derivative":{"type":"boolean","description":"true for derivative-table rows."},"footnote_ids":{"type":"array[string]","description":"Footnote ids referenced in this row."}}},"event_8k":{"description":"One 8-K / 8-K/A filing classified by official item code, normalized from the SGML index headers. Returned by /v1/events.","fields":{"accession":{"type":"string","description":"SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe. Merged at the API layer; added 2026-08-17."},"form_type":{"type":"string|null","description":"\"8-K\" or \"8-K/A\"."},"period":{"type":"string|null","description":"YYYYMMDD exactly as filed (SGML headers use this format; rule 1 — no reformatting)."},"filed_date":{"type":"string|null","description":"YYYYMMDD as filed."},"issuer":{"type":"object","description":"{name, cik} — first filer block only (multi-filer 8-Ks keep the first; documented limitation)."},"items":{"type":"array[object]","description":"[{code, caption}] — caption as filed; code is the official item number (e.g. \"2.02\") or null if the caption matches no known item."},"source_url":{"type":"string","description":"The -index-headers.html URL normalized from."},"normalized_by":{"type":"string","description":"Parser version stamp."}}},"registration_event":{"description":"One Securities Act registration-lifecycle filing (S-1/F-1 registration, amendment, EFFECT effectiveness notice, or 424B1/424B4 priced prospectus), normalized from the SGML index headers. Returned by /v1/registrations. The SEC file number threads one offering across all its stages.","fields":{"accession":{"type":"string","description":"SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe and to fetch /v1/registrations/{accession}. Merged at the API layer; added 2026-08-17."},"form_type":{"type":"string|null","description":"S-1, S-1/A, F-1, F-1/A, EFFECT, 424B1, or 424B4."},"stage":{"type":"string|null","description":"Lifecycle stage: registration | amendment | effectiveness | prospectus."},"filed_date":{"type":"string|null","description":"YYYYMMDD as filed."},"effectiveness_date":{"type":"string|null","description":"YYYYMMDD as filed; set on EFFECT notices, null otherwise."},"act":{"type":"string|null","description":"Securities act, e.g. \"1933 Act\", as filed."},"file_number":{"type":"string|null","description":"SEC file number (e.g. \"333-296288\") — shared by the registration, its amendments, the EFFECT notice, and the final prospectus of one offering."},"film_number":{"type":"string|null","description":"EDGAR film number, as filed."},"issuer":{"type":"object","description":"{name, cik, sic, sic_code, state_of_incorporation, fiscal_year_end} — all string|null, first filer block only (co-registrant filings keep the first; documented limitation)."},"former_names":{"type":"array[object]","description":"[{name, date_changed}] prior company names, as listed in the header (empty list when none)."},"source_url":{"type":"string","description":"The -index-headers.html URL normalized from."},"normalized_by":{"type":"string","description":"Parser version stamp."}}}},"transaction_codes":{"P":"Open-market purchase","S":"Open-market sale","A":"Grant/award from issuer","M":"Option exercise","F":"Shares withheld for tax on vesting/exercise","D":"Disposition to issuer (incl. going-private cash-outs)","G":"Gift","C":"Conversion of derivative","X":"In-the-money option exercise/expiration","J":"Other (see footnotes)"},"notes":["form4.accession and form4.filed_date were added 2026-08-08 (additive evolution): they are merged from the filing index at the API layer and appear on every API response and form4 webhook payload, including all historical rows.","event_8k.accession and registration_event.accession were added 2026-08-17 (same additive API-layer merge): every object served by /v1/events, /v1/registrations, and 8k/registration webhook payloads now carries the accession, including all historical rows, so source_url is no longer the only stable per-filing id.","Transaction codes are passed through verbatim from the filing; this API reports what was filed and provides no interpretation, signals, or investment advice.","Full code list: SEC Forms 3/4/5 instructions.","EFFECT notices do not state which form type they make effective, so effectiveness rows also cover non-tracked registrations (S-3, S-8, ...). Join on file_number to tie one to a tracked S-1/F-1."]}