SEC EDGAR

The SEC EDGAR dataset is the core of Thesma. It covers every US public company on NYSE and NASDAQ — under both US-GAAP and IFRS reporting — normalises XBRL financials to canonical fields, extracts structured data from narrative sections of filings, and cross-indexes everything so you can pivot from a company to its filings, financials, ratios, events, insider trades, and institutional holders in one hop.

Coverage

Dimension	Value
Companies	~6,000 active US public companies (of which ~400+ file under IFRS)
Listing scope	Every US-listed NYSE + NASDAQ issuer
Market cap coverage	~98% of investable US market cap
Filings	10-K, 10-Q, 8-K, Form 4, 13F-HR, DEF 14A, SC 13D/G, 20-F, and more
Historical financials	Typically 10+ years of annuals; quarterly since IPO or normalisation start
Normalisation	XBRL → canonical field names across filers (see XBRL mapping)

Ticker symbols and CIK numbers are interchangeable in every endpoint path. The {cik} path parameter accepts either — /v1/us/sec/companies/AAPL and /v1/us/sec/companies/0000320193 return the same company.

Known limitations

Shipped honestly. Each of these is a documented gap, not a surprise.

IFRS 20-F filers report in native presentation currency. Foreign private issuers that file 20-F (Spotify in EUR, Nu Holdings in USD, Birkenstock in EUR, and others — see the IFRS recipe for a full worked example) are covered in the canonical financials schema. Values are reported in the filer’s presentation currency with no USD conversion in v1 — client-side FX is the customer’s responsibility today. See Reporting basis and comparability for the six caveats that apply when comparing IFRS line items to US-GAAP line items.
Bank-extension line items are limited for IFRS banks. IFRS banks (Nu Holdings is the Thesma-verified example today; other foreign banks filing 20-F under IFRS are in progress) receive coverage at top-level totals — revenue, net income, assets, equity, cash flows. Sub-line-item detail lives in company-specific XBRL extension taxonomies and is planned for per-bank projects in a later release.
Delisted and acquired companies are included as historical records but are not eligible for ?include=labor_context enrichment (the BLS industry tie-out requires the company to be actively classified).
Issuers in registration (S-1) without a first-filed 10-K/10-Q appear in /v1/us/sec/companies but have empty /financials until their first periodic filing lands.

Endpoints

Each row below is a tag group from the OpenAPI spec. See the API Reference for full parameter and response schemas.

Companies

Method	Path	Purpose
GET	`/v1/us/sec/companies`	List companies (paginated). Filter by `ticker`, `search`, `sic`, `tier`, `state_fips`, `county_fips`, `exchange`, `domicile`.
GET	`/v1/us/sec/companies/{cik}`	Company detail — identity fields, optional `?include=labor_context,lending_context` enrichment.
GET	`/v1/us/sec/companies/{cik}/filings`	All filings for one company (paginated).

Filings

Method	Path	Purpose
GET	`/v1/us/sec/filings`	List filings across companies (paginated).
GET	`/v1/us/sec/filings/{accession_number}`	Filing detail — filed date, form type, source URL.
GET	`/v1/us/sec/filings/{accession_number}/content`	Full text content of the filing.

Financials

Method	Path	Purpose
GET	`/v1/us/sec/financials/fields`	Full list of canonical financial fields and their XBRL source tags.
GET	`/v1/us/sec/companies/{cik}/financials`	Income statement, balance sheet, cash flow per period.
GET	`/v1/us/sec/companies/{cik}/financials/{metric}`	Time series for a single canonical metric (e.g., `revenue`, `net_income`).

Ratios

Method	Path	Purpose
GET	`/v1/us/sec/companies/{cik}/ratios`	Computed ratios — margins, returns, leverage, growth YoY.
GET	`/v1/us/sec/companies/{cik}/ratios/{ratio}`	Time series for a single ratio.

Events

Method	Path	Purpose
GET	`/v1/us/sec/events`	Events across companies, categorised (earnings, leadership, governance, regulatory, material agreements, etc.).
GET	`/v1/us/sec/events/categories`	Event-category catalogue.
GET	`/v1/us/sec/companies/{cik}/events`	Events for one company.

Insider activity

Method	Path	Purpose
GET	`/v1/us/sec/insider-trades`	Form 4 transactions across companies.
GET	`/v1/us/sec/companies/{cik}/insider-trades`	Form 4 transactions for one company.
GET	`/v1/us/sec/companies/{cik}/insider-holdings`	Current insider beneficial-ownership snapshot.

Institutional holdings

Method	Path	Purpose
GET	`/v1/us/sec/companies/{cik}/institutional-holders`	13F holders of one company.
GET	`/v1/us/sec/companies/{cik}/institutional-changes`	Period-over-period changes in 13F holders.
GET	`/v1/us/sec/funds`	13F filers (institutional funds).
GET	`/v1/us/sec/funds/{cik}/holdings`	A fund’s reported holdings.
GET	`/v1/us/sec/funds/{cik}/holding-changes`	A fund’s period-over-period position changes.

Compensation and governance

Method	Path	Purpose
GET	`/v1/us/sec/companies/{cik}/executive-compensation`	Named-executive pay breakdown + CEO-to-median-worker ratio.
GET	`/v1/us/sec/companies/{cik}/board`	Board members from DEF 14A.
GET	`/v1/us/sec/companies/{cik}/proxy-votes`	Proxy vote results.
GET	`/v1/us/sec/companies/{cik}/beneficial-ownership`	SC 13D/13G beneficial-ownership stakes.
GET	`/v1/us/sec/beneficial-ownership`	Beneficial-ownership events across companies.

Filing sections (text extraction)

Method	Path	Purpose
GET	`/v1/us/sec/filings/{accession_number}/sections`	List sections extracted from one filing.
GET	`/v1/us/sec/filings/{accession_number}/sections/{section_type}`	One named section (e.g., Risk Factors, MD&A).
GET	`/v1/us/sec/filings/{accession_number}/sections/{section_type}/changes`	Period-over-period diffs of a section’s text.
GET	`/v1/us/sec/companies/{cik}/sections`	Cross-filing section index for one company.
GET	`/v1/us/sec/companies/{cik}/sections/{section_type}/entities`	Entities (people, companies, places) mentioned in a section across filings.
GET	`/v1/us/sec/sections/search`	Semantic search across extracted section text.

Screener

Method	Path	Purpose
GET	`/v1/us/sec/screener`	Multi-factor company screener across SEC, BLS, and SBA filters.

Data export

Method	Path	Purpose
GET	`/v1/us/sec/export/companies`	Bulk export.
GET	`/v1/us/sec/export/financials`	Bulk export.
GET	`/v1/us/sec/export/insider-trades`	Bulk export.
GET	`/v1/us/sec/export/events`	Bulk export.
GET	`/v1/us/sec/export/ratios`	Bulk export.
GET	`/v1/us/sec/export/holdings`	Bulk export.
GET	`/v1/us/sec/export/compensation`	Bulk export.
GET	`/v1/us/sec/export/beneficial-ownership`	Bulk export.

Exports stream CSV or JSONL and are available on the Business tier and above.

Cross-dataset enrichment

Two include parameters add data from adjacent verticals without a second API call. Both work on /v1/us/sec/companies/{identifier} (company detail) and on /v1/us/sec/companies/{identifier}/financials (each row in the paginated response carries the enrichment). Use the company-detail surface for a one-shot lookup; use the financials surface to align enrichment with each filing.

`?include=labor_context`

Adds a labor_context object with BLS industry data for the company’s NAICS industry — current employment, YoY change, average hourly earnings, YoY wage change, and the CES series vintage.

curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL?include=labor_context"

See the flagship recipe for the full worked example.

`?include=lending_context`

Adds a lending_context object with SBA 7(a) lending aggregates for the company’s headquarters county — loan count, total amount, charge-off rate, and jobs supported.

curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL?include=lending_context"

Both enrichments can be combined: ?include=labor_context,lending_context.

Screener filters

The /v1/us/sec/screener endpoint supports multi-factor filtering across all three datasets. Common SEC-side filters:

ticker, cik, sic, exchange, domicile, state_fips, county_fips
Financial bands: revenue_min/revenue_max, net_income_min/max, market_cap_min/max, eps_min/max
Ratio bands: gross_margin_min/max, roe_min/max, debt_to_equity_max
Growth bands: revenue_yoy_min/max, net_income_yoy_min/max
Cross-dataset: industry_employment_yoy_min (BLS), county_charge_off_rate_max (SBA)

IFRS filtering. /v1/us/sec/companies and the screener accept ?taxonomy=us-gaap or ?taxonomy=ifrs-full to narrow by reporting framework, and ?currency=EUR (or any active ISO-4217 code, case-insensitive) to narrow by presentation currency. Both parameters exclude companies with no parsed financials. Example: /v1/us/sec/companies?taxonomy=ifrs-full&currency=EUR returns IFRS filers that report in EUR (roughly 50+ today).

Run curl https://api.thesma.dev/openapi.json | jq '.paths["/v1/us/sec/screener"]' for the full parameter list — the screener’s parameter surface is large and additive.

Response envelopes

All list endpoints return the standard envelope:

{
  "data": [ /* array of entities */ ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 6005,
    "total_pages": 241
  }
}

Detail endpoints return a single entity wrapped in data:

{
  "data": { "ticker": "AAPL", "...": "..." }
}

See Pagination for iteration patterns and the semantic-search footnote.

Example: AAPL financials snapshot

curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL/financials?statement=income&period=annual&per_page=1" \
  | jq '.data[0] | {fiscal_year, line_items: {revenue: .line_items.revenue, gross_profit: .line_items.gross_profit, operating_income: .line_items.operating_income, net_income: .line_items.net_income}}'

Returns a single-period snapshot. For multi-year time series, use the {metric} endpoint or iterate with &offset= / &page=. The SEC financials recipe walks through a 5-year pull end-to-end.