{"openapi":"3.1.0","info":{"title":"SEC/EDGAR Financial Data API","description":"REST API serving SEC/EDGAR financial data — entities, filings, financials, and canonical facts.","version":"0.1.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Send API keys as: Authorization: Bearer wsh_..."}},"schemas":{}},"paths":{"/v1/health/":{"get":{"summary":"Service liveness and data-freshness check","tags":["health"],"description":"Returns 200 when the API can reach Postgres, 503 otherwise. `dataFreshness` is the max `filed_date` from `facts_raw` (null on an empty DB).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"db":{"type":"string","enum":["ok","error"]},"dataFreshness":{"type":"string","nullable":true}},"required":["status","db","dataFreshness"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"db":{"type":"string","enum":["ok","error"]},"dataFreshness":{"type":"string","nullable":true}},"required":["status","db","dataFreshness"],"additionalProperties":false}}}}}}},"/v1/me/":{"get":{"summary":"Inspect the authenticated API key and plan","tags":["access"],"description":"Returns the current caller's safe key metadata, local access state, effective plan capabilities, and non-consuming quota state.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"stripeCustomerId":{"type":"string","nullable":true}},"required":["userId","email","stripeCustomerId"],"additionalProperties":false},"key":{"type":"object","properties":{"apiKeyId":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"status":{"type":"string"},"displayPrefix":{"type":"string"},"displaySuffix":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["apiKeyId","name","status","displayPrefix","displaySuffix","expiresAt"],"additionalProperties":false},"subscription":{"type":"object","properties":{"status":{"type":"string","nullable":true},"stripeSubscriptionId":{"type":"string","nullable":true}},"required":["status","stripeSubscriptionId"],"additionalProperties":false},"plan":{"type":"object","properties":{"planCode":{"type":"string","nullable":true},"displayName":{"type":"string","nullable":true},"stripeProductId":{"type":"string","nullable":true},"stripePriceId":{"type":"string","nullable":true},"features":{"type":"object","additionalProperties":{"type":"object","properties":{"enabled":{"type":"boolean"},"value":{"nullable":true}},"required":["enabled"],"additionalProperties":false}},"limits":{"type":"object","properties":{"monthlyRequests":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"requestsPerMinute":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"historyYears":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true}},"required":["monthlyRequests","requestsPerMinute","historyYears"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"bulkAccess":{"type":"boolean"},"fullHistory":{"type":"boolean"},"prioritySupport":{"type":"boolean"},"commercialUse":{"type":"boolean"}},"required":["bulkAccess","fullHistory","prioritySupport","commercialUse"],"additionalProperties":false}},"required":["planCode","displayName","stripeProductId","stripePriceId","features","limits","capabilities"],"additionalProperties":false},"quota":{"type":"object","properties":{"available":{"type":"boolean"},"minute":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"remaining":{"type":"integer","minimum":0,"nullable":true},"resetSeconds":{"type":"integer","minimum":0}},"required":["limit","remaining","resetSeconds"],"additionalProperties":false},"month":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"remaining":{"type":"integer","minimum":0,"nullable":true},"resetSeconds":{"type":"integer","minimum":0}},"required":["limit","remaining","resetSeconds"],"additionalProperties":false}},"required":["available","minute","month"],"additionalProperties":false}},"required":["user","key","subscription","plan","quota"],"additionalProperties":false}}}}}}},"/v1/financials/":{"get":{"summary":"Query financial observations","tags":["financials"],"description":"Canonical observation endpoint. Returns one or more (company, metric, period) tuples\nin the requested layout (long, wide, grouped) with optional provenance and quality\nmetadata. Numeric values are returned as decimal strings — see \"Numeric precision\"\nin the docs. The result is bounded by tickers × metrics × period (no cursor\npagination); GET caps resolved tickers at 100, POST lifts that to\n1000 for batch use cases.\n\nasReported=true caveat: facts_canonical has no fiscal_year column, so\nperiod=FY{YYYY} on the asReported path matches by CALENDAR year of period_end.\nFor issuers whose fiscal year ends in January (e.g., Walmart FY2024 ends\n2024-01-31) the calendar-year approximation will miss the row. Use the default\npath (asReported=false) for accurate fiscal-period selection on those issuers.\n\nasof:{YYYY-MM-DD} returns a snapshot: one row per (company, metric) at the most\nrecent period_end on or before the date. On the asReported path the date filters\nfilings.filing_date (point-in-time view).","parameters":[{"schema":{"type":"string"},"in":"query","name":"tickers","required":false},{"schema":{"type":"string"},"in":"query","name":"ciks","required":false},{"schema":{"type":"string"},"in":"query","name":"sic","required":false},{"schema":{"type":"string"},"in":"query","name":"metrics","required":false},{"schema":{"type":"string","default":"latest"},"in":"query","name":"period","required":false},{"schema":{"type":"string","enum":["annual","quarterly"]},"in":"query","name":"frequency","required":false},{"schema":{"type":"string","enum":["long","wide","grouped"],"default":"long"},"in":"query","name":"layout","required":false},{"schema":{"type":"string"},"in":"query","name":"include","required":false},{"schema":{"type":"string","enum":["json","csv"],"default":"json"},"in":"query","name":"format","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"asReported","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"metric":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accession":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated metrics."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["cik","ticker","companyName","metric","periodEnd","fiscalYear","fiscalPeriod","value","unit"],"additionalProperties":false}},{"type":"array","items":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true}},"required":["cik","ticker","companyName","periodEnd","fiscalYear","fiscalPeriod"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"enum":["null"],"nullable":true}]}}},{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"metric":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accession":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated metrics."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["cik","ticker","companyName","metric","periodEnd","fiscalYear","fiscalPeriod","value","unit"],"additionalProperties":false}}}]},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"ciks":{"type":"array","items":{"type":"string"}},"sic":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"string"}},"period":{"type":"string"},"layout":{"type":"string","enum":["long","wide","grouped"]},"frequency":{"type":"string","enum":["annual","quarterly"]},"asReported":{"type":"boolean"}},"required":["metrics","period","layout","frequency","asReported"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"missing":{"type":"array","items":{"type":"string"}},"unavailableAsReported":{"type":"array","items":{"type":"string"},"description":"Requested metrics that have no as-reported XBRL fact and were omitted from this response. Only present under asReported=true when some (not all) requested metrics were dropped."},"layout":{"type":"string","enum":["long","wide","grouped"]},"period":{"type":"object","properties":{"selector":{"type":"string"},"frequency":{"type":"string","enum":["annual","quarterly"]}},"required":["selector","frequency"],"additionalProperties":false},"quality":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"completeness":{"type":"string","nullable":true},"flags":{"type":"array","items":{"type":"string"}}},"required":["completeness","flags"],"additionalProperties":false}}}},"required":["requested","returned","missing","layout","period"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}},"text/csv":{"schema":{"type":"string"}}}}}},"post":{"summary":"Batch-query financial observations (lifts URL-length cap)","tags":["financials"],"description":"Canonical observation endpoint. Returns one or more (company, metric, period) tuples\nin the requested layout (long, wide, grouped) with optional provenance and quality\nmetadata. Numeric values are returned as decimal strings — see \"Numeric precision\"\nin the docs. The result is bounded by tickers × metrics × period (no cursor\npagination); GET caps resolved tickers at 100, POST lifts that to\n1000 for batch use cases.\n\nasReported=true caveat: facts_canonical has no fiscal_year column, so\nperiod=FY{YYYY} on the asReported path matches by CALENDAR year of period_end.\nFor issuers whose fiscal year ends in January (e.g., Walmart FY2024 ends\n2024-01-31) the calendar-year approximation will miss the row. Use the default\npath (asReported=false) for accurate fiscal-period selection on those issuers.\n\nasof:{YYYY-MM-DD} returns a snapshot: one row per (company, metric) at the most\nrecent period_end on or before the date. On the asReported path the date filters\nfilings.filing_date (point-in-time view).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"ciks":{"type":"array","items":{"type":"string"}},"sic":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"string"}},"period":{"type":"string","default":"latest"},"frequency":{"type":"string","enum":["annual","quarterly"]},"layout":{"type":"string","enum":["long","wide","grouped"],"default":"long"},"include":{"type":"string"},"format":{"type":"string","enum":["json","csv"],"default":"json"},"asReported":{"type":"boolean","default":false}},"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"metric":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accession":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated metrics."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["cik","ticker","companyName","metric","periodEnd","fiscalYear","fiscalPeriod","value","unit"],"additionalProperties":false}},{"type":"array","items":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true}},"required":["cik","ticker","companyName","periodEnd","fiscalYear","fiscalPeriod"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"enum":["null"],"nullable":true}]}}},{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string","nullable":true},"companyName":{"type":"string"},"metric":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYear":{"type":"integer","nullable":true},"fiscalPeriod":{"type":"string","nullable":true},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accession":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated metrics."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["cik","ticker","companyName","metric","periodEnd","fiscalYear","fiscalPeriod","value","unit"],"additionalProperties":false}}}]},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"ciks":{"type":"array","items":{"type":"string"}},"sic":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"string"}},"period":{"type":"string"},"layout":{"type":"string","enum":["long","wide","grouped"]},"frequency":{"type":"string","enum":["annual","quarterly"]},"asReported":{"type":"boolean"}},"required":["metrics","period","layout","frequency","asReported"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"missing":{"type":"array","items":{"type":"string"}},"unavailableAsReported":{"type":"array","items":{"type":"string"},"description":"Requested metrics that have no as-reported XBRL fact and were omitted from this response. Only present under asReported=true when some (not all) requested metrics were dropped."},"layout":{"type":"string","enum":["long","wide","grouped"]},"period":{"type":"object","properties":{"selector":{"type":"string"},"frequency":{"type":"string","enum":["annual","quarterly"]}},"required":["selector","frequency"],"additionalProperties":false},"quality":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"completeness":{"type":"string","nullable":true},"flags":{"type":"array","items":{"type":"string"}}},"required":["completeness","flags"],"additionalProperties":false}}}},"required":["requested","returned","missing","layout","period"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}},"text/csv":{"schema":{"type":"string"}}}}}}},"/v1/statements/{ticker_or_cik}":{"get":{"summary":"Get bundled financial statements for one company","tags":["statements"],"description":"Convenience endpoint for a standard three-statement financial model. Returns one\ncompany, one frequency, and selected statements grouped by period. Line items are\nderived from the metric catalog statement classification and ordered by the\nserving-table model order; missing line items are omitted from each statement's\nlines array.\n\nPath token semantics: all-digits means CIK and is left-padded to 10 digits;\nanything else is treated as a case-insensitive ticker. Unresolved path tokens\nreturn NOT_FOUND because this endpoint addresses one company, not a partial\nsuccess batch.","parameters":[{"schema":{"type":"string","enum":["annual","quarterly"],"default":"annual"},"in":"query","name":"frequency","required":false},{"schema":{"type":"string","default":"last5y"},"in":"query","name":"period","required":false},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"anyOf":[{"not":{}},{"type":"array","items":{"type":"string","enum":["income_statement","balance_sheet","cash_flow"]}}]}]},"in":"query","name":"statements","required":false},{"schema":{"type":"string"},"in":"query","name":"include","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"asReported","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"ticker_or_cik","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"ticker":{"type":"string","nullable":true},"cik":{"type":"string"},"name":{"type":"string"}},"required":["ticker","cik","name"],"additionalProperties":false},"frequency":{"type":"string","enum":["annual","quarterly"]},"data":{"type":"array","items":{"type":"object","properties":{"period":{"type":"object","properties":{"label":{"type":"string"},"end":{"type":"string"}},"required":["label","end"],"additionalProperties":false},"filing":{"type":"object","properties":{"accessionNumber":{"type":"string"},"formType":{"type":"string"},"filingDate":{"type":"string"}},"additionalProperties":false},"statements":{"type":"object","properties":{"income_statement":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accessionNumber":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this line's value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated lines."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["metric","label","value","unit"],"additionalProperties":false}}},"required":["lines"],"additionalProperties":false},"balance_sheet":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accessionNumber":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this line's value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated lines."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["metric","label","value","unit"],"additionalProperties":false}}},"required":["lines"],"additionalProperties":false},"cash_flow":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"unit":{"type":"string"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["reported","calculated"]},"tag":{"type":"string"},"taxonomy":{"type":"string"},"accessionNumber":{"type":"string"},"filingUrl":{"type":"string","format":"uri","description":"Absolute https://www.sec.gov/Archives/edgar/... link to the SEC filing this line's value was extracted from. Deep-links the filing's primary document when known, falling back to the filing index page otherwise. For amended/superseded facts it points to the filing that supplied the value (e.g. the /A). Present only when kind=reported and an accession is known; absent for calculated lines."},"filingDate":{"type":"string"},"isAmendment":{"type":"boolean"},"isSuperseded":{"type":"boolean"}},"required":["kind"],"additionalProperties":false}},"required":["metric","label","value","unit"],"additionalProperties":false}}},"required":["lines"],"additionalProperties":false}},"additionalProperties":false},"quality":{"type":"object","properties":{"completeness":{"type":"string","nullable":true},"flags":{"type":"array","items":{"type":"string"}}},"required":["completeness","flags"],"additionalProperties":false}},"required":["period","statements"],"additionalProperties":false}}},"required":["company","frequency","data"],"additionalProperties":false}}}}}}},"/v1/metrics/":{"get":{"summary":"List or look up canonical metrics","tags":["metrics"],"description":"Standardized catalog of the metric keys this API understands. Use it to discover\nwhat metric keys to pass to /v1/financials, populate UI pickers, or generate\ntyped SDK enums. With no query parameters, returns the full catalog as a list\nenvelope; with ?metric=<key>, returns a single entry.\n\nFiltering (`statement`, `unitType`, `q`) is in-memory against the\ncatalog loaded at server boot; an API process restart is required to pick up\nnew seed rows.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"metric","required":false},{"schema":{"type":"string","enum":["income_statement","balance_sheet","cash_flow"]},"in":"query","name":"statement","required":false},{"schema":{"type":"string","enum":["monetary","shares","ratio","per_share","count"]},"in":"query","name":"unitType","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"statements":{"type":"array","items":{"type":"string","enum":["income_statement","balance_sheet","cash_flow"]}},"unitType":{"type":"string","enum":["monetary","shares","ratio","per_share","count"]},"isCalculated":{"type":"boolean"},"supportedFrequencies":{"type":"array","items":{"type":"string","enum":["annual","quarterly"]}}},"required":["metric","label","description","statements","unitType","isCalculated","supportedFrequencies"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},{"type":"object","properties":{"data":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"statements":{"type":"array","items":{"type":"string","enum":["income_statement","balance_sheet","cash_flow"]}},"unitType":{"type":"string","enum":["monetary","shares","ratio","per_share","count"]},"isCalculated":{"type":"boolean"},"supportedFrequencies":{"type":"array","items":{"type":"string","enum":["annual","quarterly"]}}},"required":["metric","label","description","statements","unitType","isCalculated","supportedFrequencies"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}]}}}}}}},"/v1/companies/":{"get":{"summary":"Search or list companies","tags":["companies"],"description":"Discovery surface for companies covered by the API. With no query parameters,\nreturns a deterministic, paginated cross-company listing. With `q`, matches\nagainst ticker, CIK, and company name fragments — ranking tiers run, in order:\nexact CIK, exact ticker, ticker prefix, name prefix, name substring. Substring\nmatching is gated to `q.length >= 3` to keep the seq-scan tier bounded.\n\nWithin each match tier, rows are ranked by their primary ticker's exchange\nin priority order: NASDAQ → NYSE → AMEX → NYSEArca → BATS → OTC → OTCQB →\nOTCQX → any other exchange → name-only filer (no ticker). Inside an\nexchange-priority group, rows sort alphabetically by lower(name).\n\nUse this endpoint to populate UI typeahead, resolve tickers from natural-language\ninput, or scope a downstream `/v1/financials` call by SIC.\n\nCursors are tied to the original query; clients should discard the cursor and\nrestart from page 1 when filter parameters change.","parameters":[{"schema":{"type":"string","minLength":2},"in":"query","name":"q","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"exchange","required":false},{"schema":{"type":"string"},"in":"query","name":"sic","required":false},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"integer","minimum":1,"maximum":100}]},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string","nullable":true},"cik":{"type":"string"},"name":{"type":"string"},"exchange":{"type":"string","nullable":true},"sic":{"type":"string","nullable":true},"sicDescription":{"type":"string","nullable":true}},"required":["ticker","cik","name","exchange","sic","sicDescription"],"additionalProperties":false}},"meta":{"type":"object","properties":{"returned":{"type":"integer","minimum":0},"nextCursor":{"type":"string","nullable":true}},"required":["returned","nextCursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/{ticker_or_cik}":{"get":{"summary":"Get the reference profile for one company","tags":["companies"],"description":"Single-company reference profile. Path token semantics: all-digits means CIK\nand is left-padded to 10 digits; anything else is treated as a case-insensitive\nticker. Unresolved path tokens return NOT_FOUND.\n\nReturns the DB-backed reference fields (name, primary ticker, CIK, primary\nexchange, SIC code + description, fiscal year end) plus a static\n`availableDatasets` array. Docs-spec fields without a backing data source\ntoday (CUSIP, ISIN, GICS sector/industry, MIC code, country, currency,\ndescriptions) are intentionally omitted until each upstream source lands.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"ticker_or_cik","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"ticker":{"type":"string","nullable":true},"cik":{"type":"string"},"exchange":{"type":"string","nullable":true},"sic":{"type":"string","nullable":true},"sicDescription":{"type":"string","nullable":true},"fiscalYearEnd":{"type":"string","nullable":true},"availableDatasets":{"type":"array","items":{"type":"string"}}},"required":["name","ticker","cik","exchange","sic","sicDescription","fiscalYearEnd","availableDatasets"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/v1/prices/eod":{"get":{"summary":"Query persisted end-of-day price rows","tags":["prices"],"description":"Returns persisted end-of-day price rows from the Wisesheets historical price store.\nUse period=latest for one row per ticker, period=last252d for trailing trading-day\nwindows, or period=YYYY-MM-DD..YYYY-MM-DD for paginated date ranges. Values are\nreturned as strings to preserve DECIMAL/BIGINT precision.","parameters":[{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]}]},"in":"query","name":"tickers","required":true},{"schema":{"type":"string","minLength":1},"in":"query","name":"period","required":true},{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"fields","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"integer","minimum":1,"maximum":10000}]},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"includeLive","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"date":{"type":"string"}},"required":["symbol","date"],"additionalProperties":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"period":{"type":"string"},"fields":{"type":"array","items":{"type":"string","enum":["open","low","high","close","adjClose","volume","unadjustedVolume","change","changePercent","vwap","changeOverTime","label","lastUpdated"]}},"order":{"type":"string","enum":["asc","desc"]},"includeLive":{"type":"boolean"}},"required":["tickers","period","fields","order","includeLive"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"nextCursor":{"type":"string","nullable":true},"truncated":{"type":"boolean","default":false},"missingSymbols":{"type":"array","items":{"type":"string"}},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned","nextCursor","missingSymbols"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Batch-query persisted end-of-day price rows","tags":["prices"],"description":"Returns persisted end-of-day price rows from the Wisesheets historical price store.\nUse period=latest for one row per ticker, period=last252d for trailing trading-day\nwindows, or period=YYYY-MM-DD..YYYY-MM-DD for paginated date ranges. Values are\nreturned as strings to preserve DECIMAL/BIGINT precision.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tickers":{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]},"period":{"type":"string","minLength":1},"fields":{"type":"array","items":{"type":"string"},"default":["close","adjClose","volume"]},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","minimum":1,"maximum":50000,"default":50000},"cursor":{"type":"string","minLength":1},"includeLive":{"type":"boolean","default":false}},"required":["tickers","period"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"date":{"type":"string"}},"required":["symbol","date"],"additionalProperties":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"period":{"type":"string"},"fields":{"type":"array","items":{"type":"string","enum":["open","low","high","close","adjClose","volume","unadjustedVolume","change","changePercent","vwap","changeOverTime","label","lastUpdated"]}},"order":{"type":"string","enum":["asc","desc"]},"includeLive":{"type":"boolean"}},"required":["tickers","period","fields","order","includeLive"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"nextCursor":{"type":"string","nullable":true},"truncated":{"type":"boolean","default":false},"missingSymbols":{"type":"array","items":{"type":"string"}},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned","nextCursor","missingSymbols"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/prices/live":{"get":{"summary":"Query current live quote data","tags":["prices"],"description":"Returns current quote data for in-universe symbols.\nFields default to price, changesPercentage, change, previousClose, and volume. Numeric\nquote values are returned as strings to preserve precision semantics in JSON clients.","parameters":[{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]}]},"in":"query","name":"tickers","required":true},{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"fields","required":false},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"integer","minimum":1,"maximum":25}]},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"}},"required":["symbol"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"enum":["null"],"nullable":true}]}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string","enum":["name","price","changesPercentage","change","dayLow","dayHigh","yearHigh","yearLow","marketCap","priceAvg50","priceAvg200","exchange","volume","avgVolume","open","previousClose","eps","pe","earningsAnnouncement","sharesOutstanding","timestamp"]}},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["tickers","fields","limit"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]},"missingSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Batch-query current live quote data","tags":["prices"],"description":"Returns current quote data for in-universe symbols.\nFields default to price, changesPercentage, change, previousClose, and volume. Numeric\nquote values are returned as strings to preserve precision semantics in JSON clients.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tickers":{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]},"fields":{"type":"array","items":{"type":"string"},"default":["price","changesPercentage","change","previousClose","volume"]},"limit":{"type":"integer","minimum":1,"maximum":250,"default":250}},"required":["tickers"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"}},"required":["symbol"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"enum":["null"],"nullable":true}]}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string","enum":["name","price","changesPercentage","change","dayLow","dayHigh","yearHigh","yearLow","marketCap","priceAvg50","priceAvg200","exchange","volume","avgVolume","open","previousClose","eps","pe","earningsAnnouncement","sharesOutstanding","timestamp"]}},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["tickers","fields","limit"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]},"missingSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/dividends/":{"get":{"summary":"Query historical dividend rows","tags":["dividends"],"description":"Returns per-ex-date historical dividend rows for in-universe symbols. Fields default to\nadjDividend, dividend, recordDate, and paymentDate; dividend amounts are returned as\nstrings to preserve precision. The full dividend history is fetched from the provider and\nfrom/to filtering is applied server-side on the ex-dividend date. Announced future\ndividends are included; pass to=<today> to exclude them. Rows are grouped per requested\nticker and then capped at limit, so a small limit fills earlier tickers first; when\ntruncated is true, narrow the ticker list or date window to see the rest.","parameters":[{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]}]},"in":"query","name":"tickers","required":true},{"schema":{"allOf":[{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"array","items":{"type":"string"}}]},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"fields","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"order","required":false},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"integer","minimum":1,"maximum":10000}]},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"date":{"type":"string"}},"required":["symbol","date"],"additionalProperties":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string","enum":["label","adjDividend","dividend","recordDate","paymentDate","declarationDate"]}},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["tickers","fields","from","to","order","limit"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"truncated":{"type":"boolean","default":false},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]},"missingSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Batch-query historical dividend rows","tags":["dividends"],"description":"Returns per-ex-date historical dividend rows for in-universe symbols. Fields default to\nadjDividend, dividend, recordDate, and paymentDate; dividend amounts are returned as\nstrings to preserve precision. The full dividend history is fetched from the provider and\nfrom/to filtering is applied server-side on the ex-dividend date. Announced future\ndividends are included; pass to=<today> to exclude them. Rows are grouped per requested\nticker and then capped at limit, so a small limit fills earlier tickers first; when\ntruncated is true, narrow the ticker list or date window to see the rest.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tickers":{"allOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"minItems":1}]},"fields":{"type":"array","items":{"type":"string"},"default":["adjDividend","dividend","recordDate","paymentDate"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"order":{"type":"string","enum":["asc","desc"],"default":"desc"},"limit":{"type":"integer","minimum":1,"maximum":50000,"default":50000}},"required":["tickers"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"date":{"type":"string"}},"required":["symbol","date"],"additionalProperties":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"tickers":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string","enum":["label","adjDividend","dividend","recordDate","paymentDate","declarationDate"]}},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["tickers","fields","from","to","order","limit"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"truncated":{"type":"boolean","default":false},"unknownSymbols":{"type":"array","items":{"type":"string"},"default":[]},"missingSymbols":{"type":"array","items":{"type":"string"},"default":[]}},"required":["requested","returned"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/earnings/":{"get":{"summary":"Query earnings actuals and estimates for one symbol","tags":["earnings"],"description":"Returns actual vs. estimated EPS and revenue per earnings report for one symbol, newest\nfirst. date is the earnings report (announcement) date, not a fiscal period end, and no\nfiscal period is exposed — rows cannot be joined to /v1/financials by period without\nmapping the announcement date yourself. EPS and revenue values are returned as strings to\npreserve precision, and are null for reports with no figure on file (an upcoming report has\nestimates but no actuals). limit is applied server-side after the full history is fetched,\nso truncated is exact: when it is true, raise limit to see the rest. Access is granted per\naccount; keys without it receive 403 POLICY_DENIED.","parameters":[{"schema":{"allOf":[{"type":"string"},{"type":"string","minLength":1,"maxLength":20}]},"in":"query","name":"ticker","required":true},{"schema":{"allOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"integer","minimum":1,"maximum":200}]},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"date":{"type":"string"},"epsActual":{"type":"string","nullable":true},"epsEstimated":{"type":"string","nullable":true},"revenueActual":{"type":"string","nullable":true},"revenueEstimated":{"type":"string","nullable":true},"lastUpdated":{"type":"string","nullable":true}},"required":["symbol","date","epsActual","epsEstimated","revenueActual","revenueEstimated","lastUpdated"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requested":{"type":"object","properties":{"ticker":{"type":"string"},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["ticker","limit"],"additionalProperties":false},"returned":{"type":"integer","minimum":0},"truncated":{"type":"boolean","default":false}},"required":["requested","returned"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}}},"servers":[{"url":"/","description":"Current host"}]}