sarora
Documentation → Filings and publications
Documentation

Filings and publications

Search, fetch and convert original documents into readable text.

What it is good for is on the product page: Filings and publications

POST/download/batchPOST/download/filePOST/download/filesPOST/download/{ticker_or_cik}GET/parse/{ticker_or_cik}POST/publications/downloadPOST/publications/searchGET/publications/sourcesGET/search/{ticker_or_cik}
POST /download/batch

Download Batch

Download the latest 8-K for a list of identifiers in parallel.

Each item must have exactly one of: ticker, cik, isin, wkn.

Example body:

[{"ticker": "AAPL"}, {"ticker": "AMD"}, {"isin": "US02079K3059"}, {"cik": "320193"}]

No parameters.

Example

curl -X POST "$API/download/batch" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST /download/file

Download File

Download a single SEC EDGAR file by URL and persist it locally.

The URL must point to a SEC Complete Submission Text File, e.g.:

https://www.sec.gov/Archives/edgar/data/1326801/
000162828026025108/0001628280-26-025108.txt

The MongoDB document (sec_filings collection) is updated with file_path, file_size_kb, and downloaded_at.

No parameters.

Request body SecFileRequest

NameTypeMeaning
urlstring
required		Url

Example

curl -X POST "$API/download/file" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST /download/files

Download Files

Download multiple SEC EDGAR files in parallel. Same semantics as POST /download/file but accepts a list of URL objects.

Example body:

[
  {"url": "https://www.sec.gov/Archives/edgar/data/1326801/.../0001628280-26-025108.txt"},
  {"url": "https://www.sec.gov/Archives/edgar/data/320193/.../...txt"}
]

No parameters.

Example

curl -X POST "$API/download/files" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST /download/{ticker_or_cik}

Download

Download the latest 8-K for a single identifier. Persists metadata to MongoDB.

Accepted identifier formats:

AAPL              → bare ticker
320193            → bare CIK
ticker:GOOGL      → explicit ticker prefix
cik:320193        → explicit CIK prefix
isin:US0378331005 → resolved via OpenFIGI → SEC EDGAR
wkn:623100        → resolved via OpenFIGI → SEC EDGAR
NameTypeMeaning
ticker_or_cikstring, in path
required		—

Example

curl -X POST "$API/download/SAP" \
  -H "X-API-Key: $KEY"
GET /parse/{ticker_or_cik}

Parse Filing

Parse and clean up the locally downloaded 8-K Complete Submission Text File.

  • Splits the SEC SGML container into individual document sections.
  • Strips HTML / XML / iXBRL markup from text-based sections.
  • Skips binary attachments (GRAPHIC, ZIP) and XBRL taxonomy files.
  • Returns clean plain text + metadata for every section so you can see
exactly what is embedded in the file and what is just structural markup.

Requires the file to have been downloaded first via POST /download/{ticker_or_cik}.

NameTypeMeaning
ticker_or_cikstring, in path
required		—

Example

curl "$API/parse/SAP" \
  -H "X-API-Key: $KEY"
POST /publications/download

Publications Download

Run the same routing as /publications/search, then download the first hit from the first source that returned ok.

Saves to: downloads/{source}/{identifier}/{filename}. Returns 404 if no source produced any hit.

No parameters.

Request body PublicationQuery

NameTypeMeaning
identifierstring
required		Ticker, WKN, CIK, ISIN, stock code, LEI or company name
identifierTypestring
optional		auto | ticker | wkn | cik | isin | stock_code | lei | name
countrystring
optional		ISO-2 country hint: US | DE | GB | FR | CN | HK
sourcestring
optional		Pin a specific source key from SOURCE_REGISTRY
publicationTypestring
optional		earnings | annual_report | interim_report | ad_hoc | press_release | 8k | 10q | 10k | announcement | ...
limitinteger
optional · default 10		Limit

Example

curl -X POST "$API/publications/download" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST /publications/search

Publications Search

Multi-source search for issuer publications.

Routing precedence:

1. explicit source
2. country hint
3. heuristic based on identifier shape (ISIN / WKN / CIK / stock code)

Each queried source returns its own SourceResult with status ok | not_implemented | error — the endpoint never fails just because one backend is down or unimplemented.

No parameters.

Request body PublicationQuery

NameTypeMeaning
identifierstring
required		Ticker, WKN, CIK, ISIN, stock code, LEI or company name
identifierTypestring
optional		auto | ticker | wkn | cik | isin | stock_code | lei | name
countrystring
optional		ISO-2 country hint: US | DE | GB | FR | CN | HK
sourcestring
optional		Pin a specific source key from SOURCE_REGISTRY
publicationTypestring
optional		earnings | annual_report | interim_report | ad_hoc | press_release | 8k | 10q | 10k | announcement | ...
limitinteger
optional · default 10		Limit

Example

curl -X POST "$API/publications/search" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET /publications/sources

Publications Sources

Return the full source registry with capabilities and implementation status.

No parameters.

Example

curl "$API/publications/sources" \
  -H "X-API-Key: $KEY"
GET /search/{ticker_or_cik}

Search

Look up a company by ticker or CIK and return metadata for its most recent filings. Results are persisted to MongoDB (sec_filings collection).

NameTypeMeaning
ticker_or_cikstring, in path
required		—
limitinteger, in query
optional · default 1		Number of filings to return
formstring, in query
optional		Comma-separated list of form types to filter by (e.g. `8-K`, `8-K,8-K/A`, `6-K,SC 13G,20-F`). Leave empty for all forms. Defaults to `8-K,8-K/A` if omitted.

Example

curl "$API/search/SAP" \
  -H "X-API-Key: $KEY"