{"openapi":"3.1.0","info":{"title":"Datavidence Financials API","description":"Normalized US-GAAP financial statements and SEC submissions metadata, sourced from SEC EDGAR XBRL filings. Authenticate with the `X-API-Key` header; all errors use a standard `{status, error{code, message}}` envelope.","version":"1.0.0"},"servers":[{"url":"https://financial-ledgers.api.deaddroparchives.com","description":"Production"}],"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/extract-ledger":{"get":{"summary":"Extract Ledger","operationId":"extract_ledger_v1_extract_ledger_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Four-digit fiscal year (e.g. 2023).","title":"Year"},"description":"Four-digit fiscal year (e.g. 2023)."},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"10-digit zero-padded CIK.","title":"Cik"},"description":"10-digit zero-padded CIK."},{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stock ticker (e.g. AAPL).","title":"Ticker"},"description":"Stock ticker (e.g. AAPL)."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Point-in-time date (ISO YYYY-MM-DD). Returns the figures as they were known to the SEC on or before this date (as-originally-reported, no look-ahead). Omit for the latest available (restated) view.","title":"As Of"},"description":"Point-in-time date (ISO YYYY-MM-DD). Returns the figures as they were known to the SEC on or before this date (as-originally-reported, no look-ahead). Omit for the latest available (restated) view."},{"name":"include_provenance","in":"query","required":false,"schema":{"type":"boolean","description":"Attach per-value source citations (accession, filed date, form).","default":false,"title":"Include Provenance"},"description":"Attach per-value source citations (accession, filed date, form)."},{"name":"include_ratios","in":"query","required":false,"schema":{"type":"boolean","description":"Attach computed ratios (margins, ROA/ROE, leverage) derived from the statements.","default":false,"title":"Include Ratios"},"description":"Attach computed ratios (margins, ROA/ROE, leverage) derived from the statements."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/extract-ledger/batch":{"get":{"summary":"Extract Ledger Batch","description":"Fetch normalized financials for many companies in one call.\n\nUp to 25 symbols (tickers and/or ciks) for one fiscal year. Returns per-symbol\nresults — each with either `data` or an `error` (carrying `recovery_action`) —\nso one bad symbol never fails the whole batch. Fan-out is bounded to protect\nthe shared SEC-outbound budget, and repeats are served from cache. Counts as a\nsingle request against your monthly quota.","operationId":"extract_ledger_batch_v1_extract_ledger_batch_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Four-digit fiscal year, applied to all symbols.","title":"Year"},"description":"Four-digit fiscal year, applied to all symbols."},{"name":"tickers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated tickers, e.g. AAPL,MSFT,GOOGL.","title":"Tickers"},"description":"Comma-separated tickers, e.g. AAPL,MSFT,GOOGL."},{"name":"ciks","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated CIKs (with or instead of tickers).","title":"Ciks"},"description":"Comma-separated CIKs (with or instead of tickers)."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Point-in-time date (ISO YYYY-MM-DD), applied to all symbols.","title":"As Of"},"description":"Point-in-time date (ISO YYYY-MM-DD), applied to all symbols."},{"name":"include_provenance","in":"query","required":false,"schema":{"type":"boolean","description":"Attach per-value citations to each result.","default":false,"title":"Include Provenance"},"description":"Attach per-value citations to each result."},{"name":"include_ratios","in":"query","required":false,"schema":{"type":"boolean","description":"Attach computed ratios to each result.","default":false,"title":"Include Ratios"},"description":"Attach computed ratios to each result."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/submissions":{"get":{"summary":"Get Submissions","description":"Return the trimmed SEC submissions metadata index: a lean company header\nplus a newest-first list of recent filings (columnar SEC arrays flattened\ninto rows). The heavy/irrelevant upstream fields are dropped.","operationId":"get_submissions_v1_submissions_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"10-digit zero-padded CIK.","title":"Cik"},"description":"10-digit zero-padded CIK."},{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stock ticker (e.g. AAPL).","title":"Ticker"},"description":"Stock ticker (e.g. AAPL)."},{"name":"form","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to a filing form, e.g. '10-K' (prefix match, so it also includes amendments like '10-K/A').","title":"Form"},"description":"Filter to a filing form, e.g. '10-K' (prefix match, so it also includes amendments like '10-K/A')."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of recent filings to return.","default":25,"title":"Limit"},"description":"Maximum number of recent filings to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"summary":"Usage","description":"Report the calling key's current monthly quota state.\n\nFree to call (does not consume quota) so clients can monitor consumption and\navoid hitting a hard 429. Month-aware: right after a billing-month rollover,\nusage reads 0 even before the counter is physically reset on the next\nmetered request.","operationId":"usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"BalanceSheet":{"properties":{"total_assets":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Assets"},"total_liabilities":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Liabilities"},"stockholders_equity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stockholders Equity"}},"type":"object","title":"BalanceSheet"},"BalanceSheetProvenance":{"properties":{"total_assets":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"total_liabilities":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"stockholders_equity":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]}},"type":"object","title":"BalanceSheetProvenance"},"BatchData":{"properties":{"requested":{"type":"integer","title":"Requested"},"succeeded":{"type":"integer","title":"Succeeded"},"failed":{"type":"integer","title":"Failed"},"results":{"items":{"$ref":"#/components/schemas/BatchResultItem"},"type":"array","title":"Results","default":[]}},"type":"object","required":["requested","succeeded","failed"],"title":"BatchData"},"BatchResponse":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"data":{"$ref":"#/components/schemas/BatchData"}},"type":"object","required":["data"],"title":"BatchResponse"},"BatchResultItem":{"properties":{"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik"},"status":{"type":"string","title":"Status"},"data":{"anyOf":[{"$ref":"#/components/schemas/LedgerData"},{"type":"null"}]},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorDetails"},{"type":"null"}]}},"type":"object","required":["status"],"title":"BatchResultItem","description":"One company's result within a batch: either `data` or `error` is set."},"CashFlowStatement":{"properties":{"operating_cash_flow":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Operating Cash Flow"},"investing_cash_flow":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Investing Cash Flow"},"financing_cash_flow":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Financing Cash Flow"}},"type":"object","title":"CashFlowStatement"},"CashFlowStatementProvenance":{"properties":{"operating_cash_flow":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"investing_cash_flow":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"financing_cash_flow":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]}},"type":"object","title":"CashFlowStatementProvenance"},"CompanyFiling":{"properties":{"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date"},"report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Date"},"acceptance_date_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Acceptance Date Time"},"act":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act"},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form"},"file_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Number"},"items":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Items"},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size"},"is_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Xbrl"},"is_inline_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Inline Xbrl"},"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document"},"primary_doc_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Doc Description"}},"type":"object","title":"CompanyFiling","description":"One filing row, projected from SEC's column-oriented filings.recent."},"ErrorDetails":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"recovery_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recovery Action"},"retryable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retryable"}},"type":"object","required":["code","message"],"title":"ErrorDetails"},"FinancialRatios":{"properties":{"gross_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin"},"net_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Margin"},"return_on_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Return On Assets"},"return_on_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Return On Equity"},"debt_to_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Equity"},"debt_to_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Assets"},"operating_cash_flow_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Cash Flow Margin"}},"type":"object","title":"FinancialRatios","description":"Computed ratios derived from the three statements (see app/services/ratios).\n\nEach is None when an input is missing or the denominator is zero."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IncomeStatement":{"properties":{"total_revenue":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Revenue"},"gross_profit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gross Profit"},"net_income":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Net Income"}},"type":"object","title":"IncomeStatement"},"IncomeStatementProvenance":{"properties":{"total_revenue":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"gross_profit":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]},"net_income":{"anyOf":[{"$ref":"#/components/schemas/ValueProvenance"},{"type":"null"}]}},"type":"object","title":"IncomeStatementProvenance"},"LedgerData":{"properties":{"cik":{"type":"string","title":"Cik"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"income_statement":{"$ref":"#/components/schemas/IncomeStatement"},"balance_sheet":{"$ref":"#/components/schemas/BalanceSheet"},"cash_flow_statement":{"$ref":"#/components/schemas/CashFlowStatement"},"ratios":{"anyOf":[{"$ref":"#/components/schemas/FinancialRatios"},{"type":"null"}]},"provenance":{"anyOf":[{"$ref":"#/components/schemas/LedgerProvenance"},{"type":"null"}]}},"type":"object","required":["cik","fiscal_year","income_statement","balance_sheet","cash_flow_statement"],"title":"LedgerData"},"LedgerProvenance":{"properties":{"income_statement":{"$ref":"#/components/schemas/IncomeStatementProvenance"},"balance_sheet":{"$ref":"#/components/schemas/BalanceSheetProvenance"},"cash_flow_statement":{"$ref":"#/components/schemas/CashFlowStatementProvenance"}},"type":"object","required":["income_statement","balance_sheet","cash_flow_statement"],"title":"LedgerProvenance"},"LedgerResponse":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"data":{"$ref":"#/components/schemas/LedgerData"}},"type":"object","required":["data"],"title":"LedgerResponse"},"SubmissionsData":{"properties":{"cik":{"type":"string","title":"Cik"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","default":[]},"exchanges":{"items":{"type":"string"},"type":"array","title":"Exchanges","default":[]},"sic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic"},"sic_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic Description"},"fiscal_year_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Year End"},"state_of_incorporation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Of Incorporation"},"filings_returned":{"type":"integer","title":"Filings Returned"},"filings":{"items":{"$ref":"#/components/schemas/CompanyFiling"},"type":"array","title":"Filings","default":[]}},"type":"object","required":["cik","filings_returned"],"title":"SubmissionsData"},"SubmissionsResponse":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"data":{"$ref":"#/components/schemas/SubmissionsData"}},"type":"object","required":["data"],"title":"SubmissionsResponse"},"UsageData":{"properties":{"tier":{"type":"string","title":"Tier"},"monthly_limit":{"type":"integer","title":"Monthly Limit"},"requests_this_month":{"type":"integer","title":"Requests This Month"},"requests_remaining":{"type":"integer","title":"Requests Remaining"},"resets_at":{"type":"string","title":"Resets At"}},"type":"object","required":["tier","monthly_limit","requests_this_month","requests_remaining","resets_at"],"title":"UsageData","description":"Current billing-period quota state for the calling API key."},"UsageResponse":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"data":{"$ref":"#/components/schemas/UsageData"}},"type":"object","required":["data"],"title":"UsageResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValueProvenance":{"properties":{"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession"},"filed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filed"},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form"},"unit":{"type":"string","title":"Unit","default":"USD"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"derived":{"type":"boolean","title":"Derived","default":false},"derivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Derivation"}},"type":"object","title":"ValueProvenance","description":"Source citation for a single resolved value, back to its SEC filing.\n\nPresent only when ``include_provenance=true``. Lets a consumer verify any\nnumber against the originating filing (accession + filed date + form) and\nsee the exact reporting period the value covers."}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}