# API reference

Generated from the API's OpenAPI 3.1.0 description, version 0.1.0. The base address is `https://api.secblast.com`; the routes are `GET` except those marked otherwise.

API over the v3 core filing layer. Filings, entities, search, parsed data and XBRL are read with GET. Webhook endpoints (/v3/callbacks/endpoints) and search subscriptions (/v3/search/subscriptions) are also created with POST, changed with PATCH and deleted with DELETE; the delivery routes under /v3/callbacks take POST for retry, replay, verify and test. Feedback to SEC Blast is sent with POST /v3/feedback. Lists use the envelope {data, has_more, next_cursor}. Errors are RFC 9457 application/problem+json with a stable `code`. Unknown query parameters are rejected with 400. Every response carries X-Request-Id. HEAD and OPTIONS are answered for every path. Responses that can carry values from SEC's submissions snapshot (acceptance time, report period, entity records, SEC's filing lists, tickers) have a `snapshot` block {available, date}; when available is false the response was built from the v3 database alone.

Filings that arrived live carry `status` `provisional` until SEC's nightly feed file makes them `final`.

The routes under `/v3/callbacks/` and `/v3/search/subscriptions` manage [Webhooks (API: callbacks)](https://www.secblast.com/docs/webhooks).

Each of the 82 routes has its own page. The objects they take and return are on [Schemas](https://www.secblast.com/docs/reference/schemas).

## Filings

| Route | Returns |
|---|---|
| [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) | Search filings. |
| [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) | One filing with entities, documents, events and its version chain. |
| [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) | Documents of a filing, in sequence order. |
| [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) | Stored bytes of one document. |
| [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) | Lifecycle events of a filing, oldest first. |
| [`GET /v3/filings/{accession}/header`](https://www.secblast.com/docs/reference/get-filings-accession-header) | The stored SGML header (_header.sgml) as text/plain. |
| [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) | Version chain of the filing's report: the original and every amendment, with how each amendment was linked. |
| [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) | Reports of one entity: one row per version chain (an original plus its amendments), ordered by the original filing's date, newest first (a chain whose original is not ingested is dated by its first ingested amendment). |

## Entities

| Route | Returns |
|---|---|
| [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) | Companies that are or were SPACs (blank checks, SIC 6770), from the SIC and names in their filing headers over time. |
| [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) | Entity search. |
| [`GET /v3/entities/{cik}`](https://www.secblast.com/docs/reference/get-entities-cik) | Most recent as-filed attributes of a CIK, SEC's current entity record from the snapshot (current), roles seen and filing counts. |
| [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) | SEC's own filing list for the entity (from the submissions snapshot), newest first; each row says whether v3 has the filing. |
| [`GET /v3/resolve`](https://www.secblast.com/docs/reference/get-resolve) | Which CIK(s) hold a ticker, from SEC's ticker file; with as_of, from the copy that was current on that date. |

## Full-text search

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/documents/{document}/text`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document-text) | The extracted text of one document as the full-text index holds it (text/plain; charset=utf-8): the text that snippet start/end offsets count characters of. |
| [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) | Full-text search over every document v3 holds (spec §6.1). |
| [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse) | How a query is read, without running it: the normalised query, its tree, the EDGAR reading beside the default one, prefix expansions, the structured filters after alias mapping and ticker resolution, and the index years it would touch. |
| [`GET /v3/search/status`](https://www.secblast.com/docs/reference/get-search-status) | State of the full-text index, without a key: per year the document and filing counts, index version and extractor; the live indexer's lag; indexed_through; the years being rebuilt. |

## Sections of 10-K, 10-Q and 20-F

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/sections`](https://www.secblast.com/docs/reference/get-filings-accession-sections) | The sections of a 10-K, 10-Q or 20-F: one row per item in force with its key (10k.1a, 10q.p1i2, 20f.3d), status (ok, incorporated_by_reference, combined_with, omitted, reserved, not_found), why an absent item is absent, spans and rule confidence; the amendment scope. |
| [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) | One section's canonical text, under the same serving rule, paging, ETag, cache and time limit as an 8-K item's text. |
| [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) | One section across filings, newest first (by filing date, then accession). |

## Parsed data and tables

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/parsed`](https://www.secblast.com/docs/reference/get-filings-accession-parsed) | Which parsed datasets apply to the filing (13f, 8k_items, sections) and the state of each: status (ok, ok_with_warnings, partial, unparseable, not_applicable; pending, failed or not_parsed while there is no result), the extractor version that last verified the filing and the deployed one, a re-parse in progress, warnings (at most 100), the documents read, the dataset's derive steps for the filing, and a link to the dataset's route for the filing (null while this server does not answer it). |
| [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) | Every earlier version of the filing's parsed data that is kept, newest first: each row of a dataset table a re-parse changed or removed (kind superseded: table, row key, from and to version, reason changed / removed / withdrawn, the old row), each group of rows rebuilt or replaced as a whole (kind replaced: the 13F ledger and manager-period rows, the filing's warning set and result row; the old rows) and each 13F unit decision (kind unit_decision). |
| [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) | The tables of a 10-K, 10-Q or 20-F primary document. |

## 8-K items

| Route | Returns |
|---|---|
| [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) | One 8-K item's structured events across filings, newest first (by filing date, then accession): one row per filing with its events of that item, each a list of fields {value, value_as_found, span, rule_id, rule confidence} read from the item's text; exhibit numbers joined to the filing's documents by type. |
| [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) | One 8-K item across filings, newest first (by filing date, then accession): the parsed union of header and body items, with which side named it. |
| [`GET /v3/filings/{accession}/items`](https://www.secblast.com/docs/reference/get-filings-accession-items) | An 8-K's item sets (the header's, the body's, their union), how they differ, one row per item (source, heading status, spans in the primary document, rule confidence) and the Item 9.01 exhibit rows. |
| [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) | One 8-K item's canonical text (not the filed HTML), cut from the stored primary document only when the document model and the exact bytes are at hand; otherwise text_status says why. |

## Financial data (XBRL)

| Route | Returns |
|---|---|
| [`GET /v3/companies/{cik}/periods`](https://www.secblast.com/docs/reference/get-companies-cik-periods) | One concept by fiscal period. |
| [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) | The company's breakdowns by period from its own dimensional facts: business segment, product or service, geography and major customer; revenue, operating income, assets, long-lived assets, D&A, capital expenditure and (from 2024) segment expenses. |
| [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) | The company's standard fields by period (fields x periods), from each filing's own statements through a pinned concept map: each value with its status (ok, not_reported, ambiguous, not_applicable; a blank is never a zero), the facts behind it, the rule (candidate:\<priority\> or rollup), the map version and fingerprint, and flags (failed identities, scale outliers). |
| [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) | A company's statement as presented in its latest periodic report (10-K, 10-Q, 10-KT, 10-QT, 20-F, 40-F and amendments) SEC had accepted by as_of that has one: of one kind (with its parentheticals), of one menu category (notes, details, ...) or one role URI; limit \> 1 gives the previous reports' too, newest first. |
| [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) | Every XBRL fact of a filing as filed: every instance read (the SEC-extracted one when there is one, else the filer's), facts numbered across them in reading order, each with its concept, context (entity, period, dimensions), unit, the exact value beside the filed text, decimals as filed (INF kept), nil, its duplicate class, and footnotes. |
| [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) | The filing's statements as presented: every role of the filing (with its R page), and for the roles asked -- by default the statement and cover roles; kind, category, role_no or role_uri name others, notes, policies, tables and details included -- the presentation tree in the filer's order with preferred labels, negating / total / period start and end flags, its calculation arcs, and the columns and cells assembled from the filing's facts (each cell the filed fact: exact value and filed text; a blank is null, never zero; a text block's cell says where its text is). |
| [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) | The filing's roles without their statements: every role (statements, cover, notes, policies, tables, details) in position order, with its menu category, statement kind, R page, tree size and matches_sec_render, and a link to its statement. |
| [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) | One company's facts of one concept across its filings, newest period first (then accession, fact_seq): every fact as filed, with its filing's form, filing date and acceptance time. |
| [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) | One concept and period across companies: each company's latest incarnation known at as_of (one per CIK, unit and dimension set), from one index range per filing year, the period being the filed dates. |
| [`GET /v3/financials/series`](https://www.secblast.com/docs/reference/get-financials-series) | One company's values of one concept, point in time. |
| [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) | One standard field across companies for a calendar frame (CY2024Q4, CY2024; CY2024Q4I for balance-sheet fields): each company's reported value (view latest as of a time, or first_reported) with its facts, rule, map pin and flags; in a quarter frame, a company without a reported quarter gets its quarter derived from its year, nine months, half or first quarter on one basis (monetary flows); ttm=true gives the trailing twelve months ending in the quarter. |

## Insider ownership (Forms 3, 4, 5)

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/ownership`](https://www.secblast.com/docs/reference/get-filings-accession-ownership) | A Form 3, 4 or 5 (or its /A) as filed: the document's filing-level fields, the issuer, every reporting owner with the whole address and relationship, the SEC header's entities (addresses and phone numbers), the four tables (non-derivative and derivative transactions and holdings) with each row's footnote references and footnote text, the footnotes, the signatures, and the filing's amendment chain (provisional). |
| [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) | Forms 3/4/5 holding rows (Table I and Table II) across filings, newest filing first, then table and row, with the same filing, issuer, owner and footnote members and the same views as the transactions route. |
| [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) | Forms 3/4/5 transaction rows (Table I and Table II) across filings, newest filing first, then table and row. |

## Institutional holdings (Form 13F)

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/13f`](https://www.secblast.com/docs/reference/get-filings-accession-13f) | A 13F filing's cover page (contact fields: city, state or country, ZIP code; no street line, no phone), summary page, both lists of other managers, the unit decision of its values (value_unit) and its step in the manager-period's amendment ledger. |
| [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) | The information-table rows of a 13F filing exactly as filed, in document order, with value_usd = value_reported x the unit decision's multiplier (null when the unit is ambiguous or not decided). |
| [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) | The effective 13F rows of one CUSIP across managers for one period (as known at as_of), ordered by manager CIK, ledger step and row; options are their own rows. |
| [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) | A 13F manager's holdings for one period: view=effective applies the amendment ledger (the last restatement or original, plus later additions) as known at as_of; view=as_filed lists the rows of every applied step. |
| [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) | One row per period a 13F manager filed for, newest first: ledger steps, base and latest filing, effective rows and reported 13F long value (not assets under management), flags. |

## Proposed sales (Form 144)

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/144`](https://www.secblast.com/docs/reference/get-filings-accession-144) | A Form 144 notice (or 144/A) as filed: issuer with address and phone, seller (CIK from the SEC header's reporting owner; the form names the seller only), relationships, the securities proposed to be sold with broker and approximate sale date, how they were acquired, the seller's sales of the past three months, plan adoption dates, and the notice's amendment chain on previousAccessionNumber (provisional). |
| [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) | Form 144 notices across filings, newest first, each with its securities, acquisitions and past sales. |

## Exempt offerings (Form D)

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/formd`](https://www.secblast.com/docs/reference/get-filings-accession-formd) | One Form D notice of an exempt offering as filed: offering (industry, exemptions, first sale, securities, minimum investment, the total offering amount, amount sold and remaining -- whole dollars, or Indefinite as filed -- investors, commissions, finders' fees, proceeds to related persons), every issuer, the related persons, the sales compensation recipients with their states, the header entities, and the offering chain (a D/A restates the whole notice: the chain's latest member is the offering). |
| [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) | Form D notices across filings, newest first (filing date, accession). |

## Fund holdings (Form N-PORT)

| Route | Returns |
|---|---|
| [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) | One N-PORT report as filed: registrant, series, share classes, report date, total assets, liabilities and net assets, monthly flows (sales, reinvestment, redemption) and other gains, monthly total returns per class, its place in the report ledger (an NPORT-P/A restates the whole report: one filing per series and report date is effective), and a page of its holdings in document order: identifiers (CUSIP classified -- a placeholder is never a CUSIP -- ISIN, ticker, LEI, other), balance, units, currency, value in USD, percent of net assets, asset and issuer categories, country, fair value level, and debt, repo, derivative and lending detail as filed. |
| [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) | The N-PORT holdings of one security across funds, newest filing first: exactly one of cusip (only rows whose filed CUSIP is nine characters), isin or ticker (the holding's identifiers as filed). |
| [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) | A fund series' N-PORT reports, newest report date first. |

## Datasets

| Route | Returns |
|---|---|
| [`GET /v3/datasets`](https://www.secblast.com/docs/reference/get-datasets) | The catalogue of parsed datasets: per dataset its extractor, forms, deployed version, derive steps, tables, status (available or in_preparation), coverage (the first and last filing date of successful results: a range, not a statement that every filing in it is parsed), estimated row counts, when it last changed, and its parse queue. |

## Filing stream

| Route | Returns |
|---|---|
| [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) | The filing stream: a cursor long-poll over every new, updated, corrected and deleted filing. |
| [`GET /v3/stream/status`](https://www.secblast.com/docs/reference/get-stream-status) | Stream state: the head cursor, live ingest state, sequencer lag and latency percentiles of the last hour and day. |

## Webhooks (API: callbacks)

| Route | Returns |
|---|---|
| [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) | The organization's webhook deliveries, newest first (created_at, then id), with the attempt count, the last status and error, when the next attempt is due (only while pending) and the bytes billed. |
| [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) | One delivery of the organization with its payload and every attempt (n, at, duration_ms, http_status, error_class, remote_ip, response_excerpt), oldest first. |
| [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) | Queues one more attempt of a failed delivery now (202, the delivery): it becomes pending and its attempts are not reset. |
| [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) | The organization's webhook endpoints, newest first, with limits.endpoints (the plan's limit and the active endpoints), each with its health and last 24 hours of deliveries. |
| [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) | Create a webhook endpoint. |
| [`GET /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/get-callbacks-endpoints-id) | One webhook endpoint of the organization. |
| [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) | Change a webhook endpoint. |
| [`DELETE /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/delete-callbacks-endpoints-id) | Delete a webhook endpoint. |
| [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) | Queues again the failed and dropped deliveries of one endpoint created in a window (202 {replayed, truncated, last_created_at}): oldest first, at most 10,000 a call (truncated; continue with from = last_created_at). |
| [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) | Rotate the endpoint's signing secret. |
| [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) | Sends the endpoint one sample event of a type it takes, signed like any event, with test: true in its envelope and sample data (accession 0000000000-26-000001), and answers with the attempt's outcome: 200 {id, state, delivered, http_status, error_class, duration_ms} once the one attempt is made (a test send is not retried and not billed), or 202 {id, state} when no attempt was made within 12 seconds (it is still sent; see the delivery log). |
| [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) | Sends the endpoint a new verification challenge (202, the endpoint): it is unverified, and its deliveries are held, until it answers 2xx with exactly the challenge. |
| [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) | The organization's subscriptions, newest first, with limits by kind: filter (stored kind filing), firehose and search, each the plan's limit and the active subscriptions. |
| [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) | Create a search subscription. |
| [`GET /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/get-search-subscriptions-id) | One subscription of the organization. |
| [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) | Change a search subscription. |
| [`DELETE /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/delete-search-subscriptions-id) | Delete a search subscription. |
| [`POST /v3/search/subscriptions/{id}/test`](https://www.secblast.com/docs/reference/post-search-subscriptions-id-test) | Preview a search subscription: the payloads the subscription would have produced for filings accepted in the last 7 days (at most 5, newest first), as webhook envelopes with test: true; nothing is delivered or recorded. |

## Feedback

| Route | Returns |
|---|---|
| [`POST /v3/feedback`](https://www.secblast.com/docs/reference/post-feedback) | Send feedback to SEC Blast. |

## Coverage, usage and service

| Route | Returns |
|---|---|
| [`GET /v3/coverage`](https://www.secblast.com/docs/reference/get-coverage) | Ingest coverage: per feed day the latest non-superseded ingest run and the newest complete reconcile run, overall totals, and the snapshot store. |
| [`GET /v3/coverage/count`](https://www.secblast.com/docs/reference/get-coverage-count) | The live filing count, in one small answer that needs no key, for polling: filings (final and provisional; deleted filings are not counted), provisional, deleted, documents, the newest acceptance time and, when this deployment has live ingest, the live daemon's latency over its day. |
| [`GET /v3/coverage/summary`](https://www.secblast.com/docs/reference/get-coverage-summary) | What v3 holds, in one answer that needs no key: filings by status, documents, document versions, the feed days ingested (first, last, count), filings per filing-date year, amendment links by status, the known coverage gaps (a list maintained by hand) and, when this deployment has live ingest, the live daemon's state and lag. |
| [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) | Form types present (deleted filings excluded) with filing counts, most frequent first. |
| [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) | Liveness: one database round trip, the document root, and whether the snapshot store is usable. |
| [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json) | This OpenAPI 3.1 document. |
| [`GET /v3/usage`](https://www.secblast.com/docs/reference/get-usage) | The calling key's limits and this month's usage: requests and billable response bytes (measured before compression; 5xx and 429 not billable) of its organization and of the key itself, what is left of the monthly allowance, when it starts again, and which limits are enforced. |
