{"openapi":"3.0.0","info":{"version":"4.0.0","title":"Stock Data API","description":"Stock data and simulation API. \n\n**Authentication:** This API requires an API Key via the `X-API-Key` header."},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"QuoteData":{"type":"object","properties":{"Current Price":{"type":"number","nullable":true,"example":150},"Previous Close":{"type":"number","nullable":true,"example":148.5},"Open":{"type":"number","nullable":true,"example":149},"High":{"type":"number","nullable":true,"example":151.2},"Low":{"type":"number","nullable":true,"example":148.8},"Volume":{"type":"number","nullable":true,"example":50000000},"Market Cap":{"type":"number","nullable":true,"example":2500000000000}}},"CompanyInfoData":{"type":"object","properties":{"Company Name":{"type":"string","nullable":true,"example":"Apple Inc."},"Zip Code":{"type":"string","nullable":true},"Sector":{"type":"string","nullable":true},"Industry":{"type":"string","nullable":true},"Employee Count":{"type":"integer","nullable":true},"Business Summary":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"Phone":{"type":"string","nullable":true},"State":{"type":"string","nullable":true},"Country":{"type":"string","nullable":true},"Website":{"type":"string","nullable":true},"Address":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true}}},"NewsData":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Apple announces new iPhone"},"description":{"type":"string","nullable":true},"link":{"type":"string","nullable":true},"pubDate":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true}}},"QuoteHistoryItem":{"type":"object","properties":{"date":{"type":"string","example":"2023-01-01"},"open":{"type":"number","nullable":true},"high":{"type":"number","nullable":true},"low":{"type":"number","nullable":true},"close":{"type":"number","nullable":true},"volume":{"type":"number","nullable":true},"dividends":{"type":"number","nullable":true},"stock_splits":{"type":"number","nullable":true}},"required":["date"]},"FinancialYearData":{"type":"object","properties":{"Total Revenue":{"type":"number","nullable":true},"Cost Of Revenue":{"type":"number","nullable":true},"Gross Profit":{"type":"number","nullable":true},"Ebitda":{"type":"number","nullable":true},"Net Income":{"type":"number","nullable":true},"Shares Outstanding":{"type":"number","nullable":true},"Operating Income":{"type":"number","nullable":true},"Net Interest Income":{"type":"number","nullable":true},"Interest Expense":{"type":"number","nullable":true},"Interest Income":{"type":"number","nullable":true},"Pretax Income":{"type":"number","nullable":true},"Tax Provision":{"type":"number","nullable":true},"Operating Expense":{"type":"number","nullable":true},"Total Expenses":{"type":"number","nullable":true},"Diluted EPS":{"type":"number","nullable":true},"Basic EPS":{"type":"number","nullable":true},"Diluted Average Shares":{"type":"number","nullable":true},"Basic Average Shares":{"type":"number","nullable":true},"Normalized EBITDA":{"type":"number","nullable":true},"EBIT":{"type":"number","nullable":true},"Minority Interests":{"type":"number","nullable":true},"Reconciled Depreciation":{"type":"number","nullable":true},"Research And Development":{"type":"number","nullable":true},"Selling General And Administration":{"type":"number","nullable":true},"General And Administrative Expense":{"type":"number","nullable":true},"Selling And Marketing Expense":{"type":"number","nullable":true},"Other Income Expense":{"type":"number","nullable":true},"Total Unusual Items":{"type":"number","nullable":true},"Rent Expense Supplemental":{"type":"number","nullable":true},"Restructuring And Merger And Acquisition":{"type":"number","nullable":true},"gross_profit_margin":{"type":"number","nullable":true},"net_profit_margin":{"type":"number","nullable":true},"operating_margin":{"type":"number","nullable":true},"breakeven_percent":{"type":"number","nullable":true},"eps":{"type":"number","nullable":true},"pe_ratio":{"type":"number","nullable":true},"effective_tax_rate":{"type":"number","nullable":true},"return_on_sales":{"type":"number","nullable":true},"interest_coverage":{"type":"number","nullable":true}}},"BalanceSheetData":{"type":"object","properties":{"Total Assets":{"type":"number","nullable":true},"Total Liabilities":{"type":"number","nullable":true},"Total Equity":{"type":"number","nullable":true},"Cash And Cash Equivalents":{"type":"number","nullable":true},"Total Debt":{"type":"number","nullable":true},"Net Debt":{"type":"number","nullable":true},"Working Capital":{"type":"number","nullable":true},"Inventory":{"type":"number","nullable":true},"Accounts Receivable":{"type":"number","nullable":true},"Accounts Payable":{"type":"number","nullable":true},"Retained Earnings":{"type":"number","nullable":true},"Net Tangible Assets":{"type":"number","nullable":true}}},"CashFlowData":{"type":"object","properties":{"Operating Cash Flow":{"type":"number","nullable":true},"Investing Cash Flow":{"type":"number","nullable":true},"Financing Cash Flow":{"type":"number","nullable":true},"Free Cash Flow":{"type":"number","nullable":true},"Capital Expenditure":{"type":"number","nullable":true},"Dividends Paid":{"type":"number","nullable":true},"Stock Based Compensation":{"type":"number","nullable":true},"Issuance Of Debt":{"type":"number","nullable":true},"Repayment Of Debt":{"type":"number","nullable":true}}},"KeyStatistics":{"type":"object","properties":{"enterpriseValue":{"type":"number","nullable":true},"forwardPE":{"type":"number","nullable":true},"profitMargins":{"type":"number","nullable":true},"floatShares":{"type":"number","nullable":true},"sharesOutstanding":{"type":"number","nullable":true},"sharesShort":{"type":"number","nullable":true},"heldPercentInsiders":{"type":"number","nullable":true},"heldPercentInstitutions":{"type":"number","nullable":true},"beta":{"type":"number","nullable":true},"bookValue":{"type":"number","nullable":true},"priceToBook":{"type":"number","nullable":true},"pegRatio":{"type":"number","nullable":true}}},"ScoreSimulationResponse":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/SummaryOutput"},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/DistributionBucket"}}},"required":["summary","distribution"]},"SummaryOutput":{"type":"object","properties":{"mean_score":{"type":"number","example":55.5},"std_dev":{"type":"number","example":12.2},"prob_less_than_estimate":{"type":"number","nullable":true,"example":0.45},"prob_greater_than_or_equal_estimate":{"type":"number","nullable":true,"example":0.55}},"required":["mean_score","std_dev"]},"DistributionBucket":{"type":"object","properties":{"range_start":{"type":"number","example":0},"range_end":{"type":"number","example":5},"frequency":{"type":"integer","example":150},"probability":{"type":"number","example":0.15},"cumulative_probability":{"type":"number","example":0.35}},"required":["range_start","range_end","frequency","probability","cumulative_probability"]},"ScoreSimulationRequest":{"type":"object","properties":{"num_simulations":{"type":"integer","default":10000,"example":1000},"simulation_type":{"type":"string","enum":["score"],"example":"score"},"marking_schema":{"type":"array","items":{"type":"integer"},"example":[0,25,50,75,100],"description":"Possible score values (e.g. 0%, 25%, 50%, 75%, 100%)"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionScoreInput"},"example":[{"id":"q1","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q2","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q3","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q4","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q5","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]}]},"estimated_score":{"type":"number","example":60}},"required":["simulation_type","marking_schema","questions","estimated_score"],"example":{"simulation_type":"score","num_simulations":1000,"estimated_score":60,"marking_schema":[0,25,50,75,100],"questions":[{"id":"q1","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q2","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q3","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q4","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q5","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]}]}},"QuestionScoreInput":{"type":"object","properties":{"id":{"type":"string","example":"q1"},"weight":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":1,"example":0.2},"probabilities":{"type":"array","items":{"type":"number"},"example":[0.05,0.2,0.4,0.25,0.15],"description":"Probabilities corresponding to marking_schema values (must sum to 1)"}},"required":["id","weight","probabilities"]},"CostProfitabilityResponse":{"type":"object","properties":{"mean_cost":{"type":"number","example":31500},"mean_profit_margin":{"type":"number","example":0.37},"cost_distribution":{"type":"array","items":{"$ref":"#/components/schemas/DistributionBucket"}},"profit_distribution":{"type":"array","items":{"$ref":"#/components/schemas/DistributionBucket"}}},"required":["mean_cost","mean_profit_margin","cost_distribution","profit_distribution"]},"CostProfitabilityRequest":{"type":"object","properties":{"num_simulations":{"type":"integer","default":10000,"example":1000},"simulation_type":{"type":"string","enum":["cost_profit"],"example":"cost_profit"},"revenue":{"type":"number","example":50000},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionCostInput"}}},"required":["simulation_type","revenue","questions"],"example":{"simulation_type":"cost_profit","num_simulations":1000,"revenue":50000,"questions":[{"id":"material_costs","optimistic_cost":10000,"most_likely_cost":12000,"pessimistic_cost":15000},{"id":"labor_costs","optimistic_cost":8000,"most_likely_cost":9500,"pessimistic_cost":13000},{"id":"overhead","optimistic_cost":4000,"most_likely_cost":5000,"pessimistic_cost":6000},{"id":"logistics","optimistic_cost":1500,"most_likely_cost":2000,"pessimistic_cost":3500},{"id":"marketing","optimistic_cost":2000,"most_likely_cost":3000,"pessimistic_cost":5000}]}},"QuestionCostInput":{"type":"object","properties":{"id":{"type":"string","example":"material_costs"},"optimistic_cost":{"type":"number","example":10000},"most_likely_cost":{"type":"number","example":12000},"pessimistic_cost":{"type":"number","example":15000}},"required":["id","optimistic_cost","most_likely_cost","pessimistic_cost"]}},"parameters":{}},"paths":{"/quote/{ticker}":{"get":{"tags":["Financials"],"description":"Get real-time quote data","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"}],"responses":{"200":{"description":"Quote data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteData"}}}},"500":{"description":"Server error"}}}},"/company-info/{ticker}":{"get":{"tags":["Financials"],"description":"Get company profile information","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"}],"responses":{"200":{"description":"Company info retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyInfoData"}}}},"500":{"description":"Server error"}}}},"/news/{ticker}":{"get":{"tags":["Financials"],"description":"Get recent news for a ticker","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"}],"responses":{"200":{"description":"News retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsData"}}}}},"500":{"description":"Server error"}}}},"/quote-history/{ticker}":{"get":{"tags":["Financials"],"description":"Get historical price data","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"},{"schema":{"type":"string","default":"1mo","example":"1mo","description":"Period for history (1d, 1mo, 1y...)"},"required":false,"description":"Period for history (1d, 1mo, 1y...)","name":"period","in":"query"},{"schema":{"type":"string","enum":["1m","2m","5m","15m","30m","60m","90m","1h","1d","5d","1wk","1mo","3mo"],"default":"1d","example":"1d","description":"Interval for history"},"required":false,"description":"Interval for history","name":"interval","in":"query"},{"schema":{"type":"string","example":"2023-01-01"},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","example":"2023-02-01"},"required":false,"name":"end_date","in":"query"}],"responses":{"200":{"description":"History retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/QuoteHistoryItem"}}}}},"500":{"description":"Server error"}}}},"/financials/{ticker}":{"get":{"tags":["Financials"],"description":"Get financial statements and calculated ratios","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"},{"schema":{"type":"string","example":"150.50","description":"Optional current market price for ratio calcs"},"required":false,"description":"Optional current market price for ratio calcs","name":"market_price","in":"query"},{"schema":{"type":"string","example":"2023","description":"Filter by year"},"required":false,"description":"Filter by year","name":"year","in":"query"},{"schema":{"type":"string","example":"1","description":"Filter by quarter (1-4)"},"required":false,"description":"Filter by quarter (1-4)","name":"quarter","in":"query"}],"responses":{"200":{"description":"Financials retrieved successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FinancialYearData"}}}}},"500":{"description":"Server error"}}}},"/balance-sheet/{ticker}":{"get":{"tags":["Financials"],"description":"Get balance sheet statements","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"},{"schema":{"type":"string","example":"2023","description":"Filter by year"},"required":false,"description":"Filter by year","name":"year","in":"query"},{"schema":{"type":"string","example":"1","description":"Filter by quarter (1-4)"},"required":false,"description":"Filter by quarter (1-4)","name":"quarter","in":"query"}],"responses":{"200":{"description":"Balance sheet retrieved successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/BalanceSheetData"}}}}},"500":{"description":"Server error"}}}},"/cash-flow/{ticker}":{"get":{"tags":["Financials"],"description":"Get cash flow statements","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"},{"schema":{"type":"string","example":"2023","description":"Filter by year"},"required":false,"description":"Filter by year","name":"year","in":"query"},{"schema":{"type":"string","example":"1","description":"Filter by quarter (1-4)"},"required":false,"description":"Filter by quarter (1-4)","name":"quarter","in":"query"}],"responses":{"200":{"description":"Cash flow retrieved successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CashFlowData"}}}}},"500":{"description":"Server error"}}}},"/key-statistics/{ticker}":{"get":{"tags":["Financials"],"description":"Get key statistics and valuation metrics","parameters":[{"schema":{"type":"string","example":"AAPL"},"required":true,"name":"ticker","in":"path"}],"responses":{"200":{"description":"Key statistics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyStatistics"}}}},"500":{"description":"Server error"}}}},"/simulations/score":{"post":{"tags":["Simulations"],"description":"Run monte carlo score simulation (based on open procurement assessment model)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreSimulationRequest"},"examples":{"Score Simulation":{"summary":"Standard Score Monte Carlo","value":{"simulation_type":"score","num_simulations":1000,"estimated_score":60,"marking_schema":[0,25,50,75,100],"questions":[{"id":"q1","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q2","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q3","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q4","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]},{"id":"q5","weight":0.2,"probabilities":[0.05,0.2,0.4,0.25,0.15]}]}}}}}},"responses":{"200":{"description":"Score simulation results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreSimulationResponse"}}}},"400":{"description":"Invalid input"},"500":{"description":"Server error"}}}},"/simulations/cost-profit":{"post":{"tags":["Simulations"],"description":"Run monte carlo cost & profitability simulation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostProfitabilityRequest"},"examples":{"Cost & Profit Simulation":{"summary":"Financial Risk Analysis","value":{"simulation_type":"cost_profit","num_simulations":1000,"revenue":50000,"questions":[{"id":"material_costs","optimistic_cost":10000,"most_likely_cost":12000,"pessimistic_cost":15000},{"id":"labor_costs","optimistic_cost":8000,"most_likely_cost":9500,"pessimistic_cost":13000}]}}}}}},"responses":{"200":{"description":"Cost/profit simulation results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostProfitabilityResponse"}}}},"400":{"description":"Invalid input"},"500":{"description":"Server error"}}}}}}