{"openapi":"3.1.0","info":{"title":"Beanvest financial data API","version":"1.0.0","description":"Public read-only financial data. No key required. Completed prices, explicit reporting currencies, fiscal dates, unavailable values and filing provenance. The service origin serves the current preview version."},"servers":[{"url":"https://beanvest.com"}],"paths":{"/api/v2/search":{"post":{"operationId":"searchCompanies","summary":"Search/paginate the company catalog","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":120,"default":""},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20},"offset":{"type":"integer","minimum":0,"maximum":100000,"default":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"Supported companies and available pages","content":{"application/json":{"schema":{"type":"object","required":["companies","pagination"],"properties":{"companies":{"type":"array","items":{"type":"object","required":["symbol","name","pages"],"properties":{"symbol":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR","DKK"]},"pages":{"type":"array","items":{"type":"object"}}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company/topic unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Validated snapshot unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/pages/{symbol}/{topic}":{"get":{"operationId":"getCompanyPage","summary":"Read a sourced financial page","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"}},{"name":"topic","in":"path","required":true,"schema":{"type":"string","enum":["overview","moat","fair-value","revenue","valuation","cash-flow","margins","returns","capital","deliveries","optimus"]}},{"name":"frequency","in":"query","required":false,"schema":{"type":"string","enum":["quarterly","yearly","daily"],"description":"Daily is valuation-only. Defaults to daily for valuation and the available reported frequency otherwise."}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["1Y","3Y","5Y","10Y","ALL"],"default":"5Y","description":"Valuation date range, ending at the latest available point."}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Inclusive end/close-date lower bound."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Inclusive end/close-date upper bound."}},{"name":"deductSbc","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"wacc","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"description":"WACC percentage scenario. Defaults to the company industry proxy."}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","description":"Optional single metric ID from the page definitions."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Financial chart page or versioned research page. Chart options apply only to financial topics.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FinancialPage"},{"$ref":"#/components/schemas/ResearchPage"}]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company/topic unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Validated snapshot unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/metrics":{"get":{"operationId":"getMetricDefinitions","summary":"Financial metric formulas and conventions","responses":{"200":{"description":"Metric catalog","content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object"}},"notes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company/topic unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Validated snapshot unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/companies":{"get":{"operationId":"listCompanySummaries","summary":"Complete financial-summary index","responses":{"200":{"description":"All supported company summaries and USD capitalization metadata","content":{"application/json":{"schema":{"type":"object","properties":{"companies":{"type":"array","items":{"type":"object"}},"lastCheckedAt":{"type":"string"},"capitalization":{"type":["object","null"]}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company/topic unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Validated snapshot unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/financials/{symbol}":{"get":{"operationId":"getRawFinancials","summary":"Validated dataset and complete raw filing evidence","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw dataset; larger than a page response","content":{"application/json":{"schema":{"type":"object","properties":{"dataset":{"type":"object"},"source":{"type":"string"},"lastCheckedAt":{"type":"string"},"lastValidatedAt":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company/topic unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Validated snapshot unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ResearchPage":{"type":"object","required":["research","symbol","topic","status","path","locked"],"properties":{"research":{"const":true},"symbol":{"type":"string"},"name":{"type":"string"},"topic":{"type":"string","enum":["moat","fair-value"]},"status":{"type":"string","enum":["published","stale","preview","awaiting_research","unavailable"]},"path":{"type":"string"},"locked":{"type":"boolean"},"version":{"type":["integer","null"]},"updatedAt":{"type":["string","null"]},"fairValue":{"type":["object","null"]},"moat":{"type":["object","null"]},"signals":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"type":"object"}},"history":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"statusCode":{"type":"integer"},"statusMessage":{"type":"string"},"message":{"type":"string"}}},"Pagination":{"type":"object","required":["total","limit","offset","nextOffset"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"nextOffset":{"type":["integer","null"]}}},"CapitalAllocationRow":{"type":"object","required":["period","start","end","amounts","percentages","total","complete","missing","excluded","observations"],"properties":{"period":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"amounts":{"type":"object","additionalProperties":{"type":["number","null"]},"description":"Reported cash uses in amountUnit, retaining negative reversals or net receipts."},"percentages":{"type":"object","additionalProperties":{"type":["number","null"]},"description":"Shares of available nonnegative tracked uses; missing or negative categories remain null."},"total":{"type":["number","null"],"description":"Sum of tracked nonnegative uses, or null when no positive denominator exists."},"complete":{"type":"boolean","description":"All five tracked categories available and nonnegative; not all company cash flows."},"missing":{"type":"array","items":{"type":"string","enum":["capex","acquisitions","buybacks","dividends","debt_repayments"]}},"excluded":{"type":"array","items":{"type":"string","enum":["capex","acquisitions","buybacks","dividends","debt_repayments"]},"description":"Negative payments excluded from the stack."},"observations":{"type":"object","description":"Raw values, methods and fundamental-fact indices resolved through rawDataPath."},"debtScope":{"type":["string","null"],"enum":["aggregate","long_term","convertible",null],"description":"Scope of the selected repayment concept; debt components are never added to an overlapping aggregate."}}},"FinancialPage":{"type":"object","required":["schemaVersion","company","topic","options","definitions","rows","pagination","sources","notes"],"properties":{"capitalAllocation":{"type":"object","description":"Cash-flow topics only; tracked uses, with the same dates and pagination as rows.","properties":{"amountUnit":{"type":"string"},"percentageUnit":{"const":"percent"},"formula":{"type":"string"},"definitions":{"type":"array","items":{"type":"object"}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/CapitalAllocationRow"}},"latest":{"anyOf":[{"$ref":"#/components/schemas/CapitalAllocationRow"},{"type":"null"}]}}},"schemaVersion":{"const":1},"company":{"type":"object","required":["symbol","name","currency"],"properties":{"symbol":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR","DKK"]}}},"topic":{"type":"string","enum":["overview","moat","fair-value","revenue","valuation","cash-flow","margins","returns","capital","deliveries","optimus"]},"path":{"type":"string"},"options":{"type":"object"},"definitions":{"type":"array","items":{"type":"object","required":["id","label","unit","formula"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"unit":{"type":"string","description":"Explicit currency_millions, shares_millions, currency_per_share, percent, percentage_points, multiple, vehicles or robots."},"formula":{"type":"string"}}}},"rows":{"type":"array","items":{"type":"object","required":["period","end","values","issues"],"properties":{"period":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"priceDate":{"type":"string","format":"date"},"basisEnd":{"type":"string","format":"date"},"partial":{"type":"boolean"},"values":{"type":"object","additionalProperties":{"type":["number","null"]}},"issues":{"type":"object","additionalProperties":{"type":"string"}}}}},"statistics":{"type":"object","description":"Selected-range statistics before pagination; includes relative historical comparison."},"pagination":{"$ref":"#/components/schemas/Pagination"},"sources":{"type":"array","items":{"type":"object"}},"notes":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"lastValidatedAt":{"type":"string"},"lastCheckedAt":{"type":"string"},"rawDataPath":{"type":"string"}}}}}}