{ "openapi": "3.1.0", "info": { "title": "Sahm Screener — Saudi Stock Data API", "description": "Fundamental financial data for 394 companies on Saudi Arabia's Tadawul and Nomu markets. Sourced from CMA-mandated XBRL filings. Updated nightly.", "version": "1.0.0", "contact": { "name": "Sahm Screener", "url": "https://sahmscreener.com", "email": "hello@sahmscreener.com" } }, "servers": [ { "url": "https://sahmscreener.com", "description": "Production" } ], "paths": { "/api/llm/screener": { "get": { "operationId": "getAllCompanies", "summary": "Get all 394 Saudi-listed companies with key financial metrics", "description": "Returns financial data for all 394 Saudi companies on Tadawul and Nomu. Use for: top performers, best ROE/margins/growth, sector analysis, dividend payers, screening by any metric, or comparing multiple companies.", "responses": { "200": { "description": "All companies with key financial metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "data_origin": { "type": "string" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Tadawul ticker symbol" }, "name": { "type": "string", "description": "Company name in English" }, "sector": { "type": "string", "description": "GICS sector classification" }, "market": { "type": "string", "description": "Tadawul or Nomu" }, "period": { "type": "string", "description": "Fiscal period e.g. Annual-2024" }, "revenue_sar": { "type": "number", "description": "Total revenue in SAR" }, "net_profit_sar": { "type": "number", "description": "Net profit in SAR" }, "net_margin_pct": { "type": "number", "description": "Net profit margin percentage" }, "gross_margin_pct": { "type": "number", "description": "Gross margin percentage" }, "roe_pct": { "type": "number", "description": "Return on equity percentage" }, "revenue_growth_yoy_pct": { "type": "number", "description": "Year-over-year revenue growth percentage" }, "earnings_quality": { "type": "string", "description": "Exceptional, High, Moderate, or Low based on cash conversion ratio" }, "profile_url": { "type": "string", "description": "Full company profile page on Sahm Screener" } } } }, "attribution": { "type": "object", "properties": { "cite_as": { "type": "string" }, "data_source": { "type": "string" }, "license": { "type": "string" } } } } } } } } } } }, "/api/llm/company/{symbol}": { "get": { "operationId": "getCompanyBySymbol", "summary": "Get detailed multi-year financials for a specific Saudi company", "description": "Returns full financial history for one company. Use for single company questions. Key symbols: Aramco=2222, STC=7010, AlRajhi=1120, SABIC=2010, SNB=1180, Maaden=1211, Almarai=2280, Jarir=4190.", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Tadawul ticker symbol (e.g. 2222 for Saudi Aramco, 7010 for STC, 1120 for Al Rajhi Bank)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full company financials with multi-year history", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "data_origin": { "type": "string" }, "last_updated": { "type": "string", "description": "Date of most recent filing" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "sector": { "type": "string" }, "market": { "type": "string" }, "profile_url": { "type": "string" } } }, "financials": { "type": "array", "description": "Annual financial data, most recent first", "items": { "type": "object", "properties": { "period": { "type": "string" }, "fiscal_year_end": { "type": "string" }, "revenue_sar": { "type": "number" }, "net_profit_sar": { "type": "number" }, "operating_profit_sar": { "type": "number" }, "gross_profit_sar": { "type": "number" }, "total_assets_sar": { "type": "number" }, "total_equity_sar": { "type": "number" }, "total_debt_sar": { "type": "number" }, "operating_cash_flow_sar": { "type": "number" }, "free_cash_flow_sar": { "type": "number" }, "eps_sar": { "type": "number" }, "roe_pct": { "type": "number" }, "roa_pct": { "type": "number" }, "net_margin_pct": { "type": "number" }, "gross_margin_pct": { "type": "number" }, "operating_margin_pct": { "type": "number" }, "revenue_growth_yoy_pct": { "type": "number" }, "cash_conversion_ratio": { "type": "number" }, "earnings_quality": { "type": "string" } } } }, "cagr": { "type": "object", "description": "Compound annual growth rates over multiple periods", "properties": { "revenue_2yr_cagr_pct": { "type": "number" }, "revenue_3yr_cagr_pct": { "type": "number" }, "revenue_4yr_cagr_pct": { "type": "number" }, "profit_2yr_cagr_pct": { "type": "number" }, "profit_3yr_cagr_pct": { "type": "number" }, "profit_4yr_cagr_pct": { "type": "number" } } }, "attribution": { "type": "object", "properties": { "cite_as": { "type": "string" }, "data_source": { "type": "string" }, "license": { "type": "string" } } } } } } } }, "404": { "description": "Company not found" } } } }, "/api/llm/companies": { "get": { "operationId": "getCompanyList", "summary": "Get list of all 394 Saudi-listed companies with symbols and sectors", "description": "Lists all 394 Saudi-listed companies with symbols and sectors. Use to find a ticker symbol or look up which companies exist before calling getCompanyBySymbol.", "responses": { "200": { "description": "List of all companies", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "data_origin": { "type": "string" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "market": { "type": "string" }, "profile_url": { "type": "string" }, "data_url": { "type": "string" } } } }, "attribution": { "type": "object", "properties": { "cite_as": { "type": "string" }, "data_source": { "type": "string" }, "license": { "type": "string" } } } } } } } } } } } } }