{ "openapi": "3.0.3", "info": { "title": "SouqData API", "version": "1.0.0", "description": "Programmatic access to GCC + MENA stock market data, governance analytics, Islamic finance screening, and AI-powered research. 1,937 companies across 11 exchanges, 94+ analytics engines, 170+ insight pages, 7 tool pages, 125 copilot tools, and pgvector semantic search across 6,311+ announcements.", "contact": { "name": "SouqData", "url": "https://souqdata.com/developers" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://souqdata.com", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Companies", "description": "Company listings and profiles" }, { "name": "Screener", "description": "Stock screener with 212+ filterable columns" }, { "name": "People", "description": "Directors, officers, and board network" }, { "name": "Valuation", "description": "Fair value, earnings quality, and financial distress scoring" }, { "name": "Dividends", "description": "Dividend safety and history" }, { "name": "Governance", "description": "Board governance, CMA compliance, and board succession" }, { "name": "Islamic Finance", "description": "Shariah compliance, sukuk instruments, and zakat estimation" }, { "name": "GCC Intelligence", "description": "Nationalization compliance, deal signals, giga-project exposure" }, { "name": "IR & Analyst", "description": "Investor relations dashboard, briefing, rehearsal, and QA tools" }, { "name": "Portfolio", "description": "Portfolio screening, backtesting, and analyst notes" }, { "name": "AI", "description": "AI copilot (SSE), MCP server (JSON-RPC), deep research, semantic search" }, { "name": "Embeds", "description": "Widgets, badges, and embeddable components" }, { "name": "Signals", "description": "Technical signals, insider clusters, and investment profile scoring" }, { "name": "Social", "description": "Social sentiment from news and social media" }, { "name": "Compliance", "description": "KYC/AML compliance, UBO analysis, PEP screening" } ], "paths": { "/api/v1/semantic-search": { "get": { "operationId": "semanticSearch", "summary": "Semantic Search", "description": "AI-powered semantic similarity search across 6,311+ GCC announcements using pgvector embeddings. Supports two modes: 'semantic' (vector-only) and 'hybrid' (vector + text + Reciprocal Rank Fusion). 100+ financial synonym groups including Arabic terms. Filters by ticker, exchange, document type, language, and date range.", "tags": ["AI"], "parameters": [ {"name": "q", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Natural language search query (English or Arabic)"}, {"name": "mode", "in": "query", "schema": {"type": "string", "enum": ["semantic", "hybrid"], "default": "semantic"}, "description": "Search mode"}, {"name": "ticker", "in": "query", "schema": {"type": "string"}, "description": "Filter by ticker symbol"}, {"name": "exchange", "in": "query", "schema": {"type": "string"}, "description": "Filter by exchange code (TDWL, DFM, ADX, etc.)"}, {"name": "type", "in": "query", "schema": {"type": "string"}, "description": "Filter by document type (announcement, annual_report, agm)"}, {"name": "language", "in": "query", "schema": {"type": "string", "enum": ["en", "ar"]}, "description": "Filter by language"}, {"name": "from", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Start date filter (YYYY-MM-DD)"}, {"name": "to", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "End date filter (YYYY-MM-DD)"}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 20}, "description": "Max results"}, {"name": "threshold", "in": "query", "schema": {"type": "number", "default": 0.4}, "description": "Minimum similarity threshold (0-1)"} ], "responses": { "200": { "description": "Search results with similarity scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": {"type": "array", "items": {"type": "object", "properties": {"announcement_id": {"type": "string"}, "ticker": {"type": "string"}, "exchange_code": {"type": "string"}, "headline": {"type": "string"}, "announcement_date": {"type": "string"}, "announcement_type": {"type": "string"}, "snippet": {"type": "string"}, "similarity": {"type": "number"}, "language": {"type": "string"}}}}, "total": {"type": "integer"}, "query": {"type": "string"}, "mode": {"type": "string"}, "synonyms": {"type": "array", "items": {"type": "object"}} } } } } } } } }, "/api/deep-research/{ticker}": { "get": { "operationId": "deepResearch", "summary": "Deep Research Report", "description": "8-section SSE research report powered by Claude Haiku 4.5. Fetches 19 data sources in parallel. Sections: Company Overview, Financial Analysis, Board & Governance, Risk Assessment, Market Position, Key Findings, Islamic Finance & Compliance, GCC Market Context.", "tags": [ "AI" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "SSE stream of report sections", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/accounting-quality/{ticker}": { "get": { "operationId": "getAccountingQuality", "summary": "Accounting Quality", "description": "Forensic accounting analysis using Beneish M-Score, Sloan Accruals Ratio, and a composite quality score. Flags earnings manipulation risk.", "tags": [ "Valuation" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Accounting quality scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountingQuality" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agm-outcomes/{ticker}": { "get": { "operationId": "getAGMOutcomes", "summary": "AGM Outcomes", "description": "Fetch AGM resolutions and voting outcomes for a company.", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker" } ], "responses": { "200": { "description": "AGM outcomes", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string" }, "total_resolutions": { "type": "integer" }, "controversial_count": { "type": "integer" }, "pass_rate": { "type": "number" }, "resolutions": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/analyst-notes": { "get": { "operationId": "listAnalystNotes", "summary": "List Analyst Notes", "description": "CRUD for research notes. Owner-only access via x-user-id header.", "tags": [ "Portfolio" ], "parameters": [ { "name": "entity_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by entity type" }, { "name": "entity_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by entity ID" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Full-text search" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Max results" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Analyst notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } }, "post": { "operationId": "createAnalystNote", "summary": "Create Analyst Note", "description": "Create a new research note attached to a company or director.", "tags": [ "Portfolio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "entity_id", "title", "content" ], "properties": { "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } } } } }, "/api/v1/analyst-notes/{noteId}": { "get": { "operationId": "getAnalystNote", "summary": "Get Analyst Note", "description": "Retrieve a specific analyst research note by ID.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Note UUID" }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "responses": { "200": { "description": "Analyst note", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "patch": { "operationId": "updateAnalystNote", "summary": "Update Analyst Note", "description": "Update an analyst research note.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated note" } } }, "delete": { "operationId": "deleteAnalystNote", "summary": "Delete Analyst Note", "description": "Delete an analyst research note.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/v1/ask": { "post": { "operationId": "askCopilot", "summary": "AI Copilot", "description": "Natural language query interface powered by Claude Sonnet 4. Streams responses via Server-Sent Events (SSE). Supports multi-round tool calling with 38 data tools. Bilingual (English/Arabic).", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language question" }, "conversation_id": { "type": "string", "description": "Continue a conversation" }, "lang": { "type": "string", "enum": [ "en", "ar" ], "description": "Response language" } } } } } }, "responses": { "200": { "description": "SSE stream of response chunks", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/api/v1/audit-opinions": { "get": { "operationId": "getAuditOpinions", "summary": "Audit Opinion Analysis", "description": "Market-wide audit opinion analysis: going concern detection, Key Audit Matters (KAMs) by ISA 701 theme, modified opinion tracking, Big4 vs mid-tier classification, risk scoring.", "tags": [ "Risk" ], "responses": { "200": { "description": "Audit opinion analysis across all companies" } } } }, "/api/v1/audit-opinions/{ticker}": { "get": { "operationId": "getAuditOpinionForTicker", "summary": "Company Audit Opinion", "description": "Audit opinion details for a specific company including going concern flags, KAMs, auditor info, and opinion history.", "tags": [ "Risk" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Company audit opinion details" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/backtest": { "get": { "operationId": "backtest", "summary": "Strategy Backtester", "description": "Backtest factor-based strategies with annual rebalancing. 40+ fundamental metrics, equal/market-cap/inverse weighting, Sharpe/Sortino/max drawdown.", "tags": [ "Portfolio" ], "parameters": [ { "name": "strategy", "in": "query", "schema": { "type": "string" }, "description": "Strategy type" }, { "name": "metric", "in": "query", "schema": { "type": "string" }, "description": "Fundamental metric to rank by" }, { "name": "tickers", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated ticker list" }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Backtest start date" }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Backtest end date" } ], "responses": { "200": { "description": "Backtest results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } } } } }, "/api/v1/badge": { "get": { "operationId": "getBadge", "summary": "Governance Badge", "description": "SVG governance badge for embedding. CORS-enabled, 5-minute cache.", "tags": [ "Embeds" ], "security": [], "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "theme", "in": "query", "schema": { "type": "string", "enum": [ "light", "dark" ], "default": "light" }, "description": "Badge theme" }, { "name": "style", "in": "query", "schema": { "type": "string", "enum": [ "full", "compact" ], "default": "full" }, "description": "Badge style" } ], "responses": { "200": { "description": "SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/board-certifications/{ticker}": { "get": { "operationId": "getBoardCertifications", "summary": "Board Certifications", "description": "Director qualifications and governance certifications for a company's board.", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Board certifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BoardCertification" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/board-succession/{ticker}": { "get": { "operationId": "getBoardSuccession", "summary": "Board Succession Risk", "description": "Evaluates board renewal risk based on tenure, age, committee gaps, and succession pipeline.", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Succession risk analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BoardSuccession" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/claim-profile": { "post": { "operationId": "claimProfile", "summary": "Claim Company Profile", "description": "Submit a company profile claim request with corporate email verification. For IR teams to claim and manage their company page.", "tags": [ "Companies" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Company ticker" }, "email": { "type": "string", "description": "Corporate email address" } }, "required": [ "ticker", "email" ] } } } }, "responses": { "200": { "description": "Claim submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "ticker": { "type": "string" }, "company": { "type": "string" } } } } } } } } }, "/api/v1/cma-governance/{ticker}": { "get": { "operationId": "getCMAGovernance", "summary": "CMA Governance Compliance", "description": "Saudi CMA Corporate Governance Regulations compliance assessment. 21 articles scored. Tadawul-listed companies only.", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tadawul ticker symbol" } ], "responses": { "200": { "description": "CMA compliance assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CMAGovernance" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/companies": { "get": { "operationId": "listCompanies", "summary": "List Companies", "description": "Returns all active GCC-listed companies. Optionally filter by search query or GICS sector.", "tags": [ "Companies" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search by company name or ticker" }, { "name": "sector", "in": "query", "schema": { "type": "string" }, "description": "Filter by GICS sector (e.g. \"Financials\", \"Real Estate\")" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Response language (adds _ar fields when ar)" } ], "responses": { "200": { "description": "Company list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } } } } } }, "/api/v1/companies/{ticker}": { "get": { "operationId": "getCompany", "summary": "Company Detail", "description": "Full company profile including financials, directors, dividends, and key metrics.", "tags": [ "Companies" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol (e.g. \"EMAAR\", \"QNB\")" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Response language" } ], "responses": { "200": { "description": "Company detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyDetail" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/compliance/{ticker}": { "get": { "operationId": "getComplianceAssessment", "summary": "Compliance Assessment", "description": "Multi-dimensional compliance scoring aggregating governance scorecard, CMA governance, and risk assessment for a company.", "tags": [ "Compliance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker" } ], "responses": { "200": { "description": "Compliance assessment", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/deal-insider-signals/{ticker}": { "get": { "operationId": "getDealInsiderSignals", "summary": "Deal & Insider Signals", "description": "Pre-deal insider trading pattern detection. Analyzes volume anomalies and insider activity in the lead-up to corporate events.", "tags": [ "GCC Intelligence" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "minimum": 1, "maximum": 365 }, "description": "Lookback period in days" } ], "responses": { "200": { "description": "Insider signal analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealInsiderSignals" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/degrees-of-separation": { "get": { "operationId": "getDegreesOfSeparation", "summary": "Degrees of Separation", "description": "Find the shortest board network path between two directors using BFS across shared board seats. Max depth: 6.", "tags": [ "People" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Source director ID" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target director ID" } ], "responses": { "200": { "description": "Network path result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DegreesOfSeparation" } } } } } } } } }, "/api/v1/directors": { "get": { "operationId": "searchDirectors", "summary": "Search Directors", "description": "Search directors by name or list current board members for a specific company.", "tags": [ "People" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search by director name" }, { "name": "ticker", "in": "query", "schema": { "type": "string" }, "description": "List directors for a specific company" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Max results" } ], "responses": { "200": { "description": "Director list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Director" } } } } } } } } } }, "/api/v1/dividend-safety/{ticker}": { "get": { "operationId": "getDividendSafety", "summary": "Dividend Safety Score", "description": "Composite dividend safety assessment based on payout ratio, coverage, streak, DPS trend, and earnings stability.", "tags": [ "Dividends" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Dividend safety score", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DividendSafety" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/export/governance-report/{ticker}": { "get": { "operationId": "exportGovernanceReport", "summary": "Export Governance Report", "description": "Generate and export governance gap report as JSON or PDF.", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "pdf" ], "default": "json" }, "description": "Export format" } ], "responses": { "200": { "description": "Governance report (JSON or PDF binary)" } } } }, "/api/v1/export/screener": { "get": { "operationId": "exportScreener", "summary": "Export Screener (XLSX)", "description": "Export filtered screener data as XLSX workbook with 2 sheets: Screener data + Metadata.", "tags": [ "Screener" ], "parameters": [ { "name": "exchange", "in": "query", "schema": { "type": "string" }, "description": "Filter by exchange code" }, { "name": "sector", "in": "query", "schema": { "type": "string" }, "description": "Filter by sector" }, { "name": "cols", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated column list" } ], "responses": { "200": { "description": "XLSX file", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/fair-value/{ticker}": { "get": { "operationId": "getFairValue", "summary": "Fair Value Estimate", "description": "Three-model valuation: DCF (discounted cash flow), DDM (dividend discount model), and EV/EBITDA relative valuation. Returns consensus estimate and upside/downside percentage.", "tags": [ "Valuation" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Fair value estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FairValue" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/filing-diff": { "get": { "operationId": "getFilingDiff", "summary": "Filing Diff Comparison", "description": "Structured filing comparison between two financial years across 9 data sources (income statement, balance sheet, governance, directors, shareholders, attendance, executive compensation, auditor, announcements). Returns section-by-section diffs with severity badges.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "fy_a", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "First financial year for comparison (e.g. 2023)" }, { "name": "fy_b", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Second financial year for comparison (e.g. 2024)" } ], "responses": { "200": { "description": "Filing diff results", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "fy_a": { "type": "integer" }, "fy_b": { "type": "integer" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "none" ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value_a": {}, "value_b": {}, "change_pct": { "type": "number" } } } } } } } } } } } } } } }, "/api/v1/financial-distress/{ticker}": { "get": { "operationId": "getFinancialDistress", "summary": "Financial Distress", "description": "Bankruptcy probability using Altman Z-Score (original and adjusted) and Piotroski F-Score.", "tags": [ "Valuation" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Distress analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FinancialDistress" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/giga-project-exposure/{ticker}": { "get": { "operationId": "getGigaProjectExposure", "summary": "Vision 2030 Giga-Project Exposure", "description": "Measures a company's contractual exposure to Saudi Vision 2030 giga-projects (NEOM, Red Sea Global, Qiddiya, ROSHN, Diriyah Gate, King Salman Park, Jeddah Tower, The Line). Returns exposure percentage, contract count, and project breakdown.", "tags": [ "GCC Intelligence" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Giga-project exposure analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GigaProjectExposure" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/governance-v2/{ticker}": { "get": { "summary": "Governance Risk Score v2", "description": "5 sub-scores: Board Quality, Leadership, Oversight, Accountability, Transparency. Multi-factor governance risk scoring.", "operationId": "getGovernanceV2", "tags": [ "Governance" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ARAMCO" } ], "responses": { "200": { "description": "Governance v2 score", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/insider-clusters/{ticker}": { "get": { "summary": "Insider cluster detection", "description": "Temporal clustering of insider trades. Detects coordinated buying/selling patterns, unanimity, magnitude, and frequency.", "operationId": "getInsiderClusters", "tags": [ "Signals" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "EMAAR" } ], "responses": { "200": { "description": "Insider cluster data", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/investment-profile/{ticker}": { "get": { "summary": "Investment profile radar", "description": "5-axis radar: Value, Growth, Profitability, Safety, Momentum. Composite scoring with percentile ranks.", "operationId": "getInvestmentProfile", "tags": [ "Valuation" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "STC" } ], "responses": { "200": { "description": "Investment profile", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/investor-qa/{ticker}": { "get": { "operationId": "getInvestorQA", "summary": "Investor Q&A Simulator", "description": "AI-generated hardest investor questions across 13 GCC-specific categories. Powered by Claude Haiku.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Generated investor questions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvestorQA" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ir-briefing/{ticker}": { "get": { "operationId": "getIRBriefing", "summary": "IR Briefing", "description": "Structured briefing with 10-point change detection diff engine. Pass previous briefing data to detect changes.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "previous", "in": "query", "schema": { "type": "string" }, "description": "JSON-encoded previous briefing data for change detection" } ], "responses": { "200": { "description": "IR briefing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ir-dashboard/{ticker}": { "get": { "operationId": "getIRDashboard", "summary": "IR Dashboard", "description": "9-source IR data aggregator: sentiment, shareholders, insider activity, governance, earnings, disclosure quality, peers, and consensus.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "IR dashboard data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ir-rehearsal/{ticker}": { "post": { "operationId": "postIRRehearsal", "summary": "IR Rehearsal", "description": "Analyze a draft announcement for language risks, sentiment, media pickup potential, readability, and buzzwords. Pure regex \u2014 $0 cost.", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_text" ], "properties": { "draft_text": { "type": "string", "minLength": 20, "maxLength": 100000, "description": "Draft announcement text to analyze" } } } } } }, "responses": { "200": { "description": "Rehearsal analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IRRehearsal" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/keys": { "get": { "operationId": "listAPIKeys", "summary": "List API Keys", "description": "List API keys and usage statistics for the authenticated user.", "tags": [ "AI" ], "parameters": [ { "name": "usage", "in": "query", "schema": { "type": "string" }, "description": "Key ID to get usage for" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30 }, "description": "Usage lookback days" } ], "responses": { "200": { "description": "API keys and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object" } } } } } } } }, "post": { "operationId": "createAPIKey", "summary": "Create API Key", "description": "Generate a new API key (Enterprise+ tier required).", "tags": [ "AI" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "New API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "apiKey": { "type": "string" }, "keyPrefix": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string" } } } } } } } }, "delete": { "operationId": "revokeAPIKey", "summary": "Revoke API Key", "description": "Revoke an existing API key.", "tags": [ "AI" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" } }, "required": [ "keyId" ] } } } }, "responses": { "200": { "description": "Key revoked" } } } }, "/api/v1/mcp": { "post": { "operationId": "mcpCall", "summary": "MCP Server", "description": "Model Context Protocol (JSON-RPC 2.0) server with 38 tools. Compatible with Claude Desktop and Claude Code.", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string", "description": "MCP method (tools/list, tools/call)" }, "params": { "type": "object" }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "operationId": "mcpInfo", "summary": "MCP Server Info", "description": "Returns server info and tool count.", "tags": [ "AI" ], "responses": { "200": { "description": "Server info", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/nationalization-compliance/{ticker}": { "get": { "operationId": "getNationalizationCompliance", "summary": "Nationalization Compliance", "description": "Workforce nationalization quota compliance: Nitaqat (Saudi), Emiratization (UAE), Omanization, Qatarization, Bahrainization, Jordanization.", "tags": [ "GCC Intelligence" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Nationalization compliance data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NationalizationCompliance" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/officers/{ticker}": { "get": { "operationId": "getOfficers", "summary": "Officers", "description": "Combined board members and executive management for a company. Filter by type ('board'/'executive') using is_board_role, or by status ('Current'/'Former'). Includes permanent person IDs for cross-referencing.", "tags": [ "People" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "board", "executive" ] }, "description": "Filter by officer type" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "current", "former" ] }, "description": "Filter by appointment status" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Appointed after this date" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Appointed before this date" } ], "responses": { "200": { "description": "Officers list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "officers": { "type": "array", "items": { "$ref": "#/components/schemas/Officer" } }, "total_count": { "type": "integer" }, "current_count": { "type": "integer" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ownership-alerts": { "get": { "operationId": "getOwnershipAlerts", "summary": "Ownership Flow Alerts", "description": "Returns ownership flow alerts across all issuers. 7 alert types (foreign spike/drop, new/departed substantial holder, SWF position change, concentration increase, institutional shift) with 4 severity levels.", "tags": [ "GCC Intelligence" ], "parameters": [ { "name": "ticker", "in": "query", "schema": { "type": "string" }, "description": "Filter by ticker symbol" }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "description": "Filter by alert severity" } ], "responses": { "200": { "description": "Ownership alerts", "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "alert_type": { "type": "string" }, "severity": { "type": "string" }, "description": { "type": "string" }, "change_pct": { "type": "number" } } } }, "meta": { "type": "object", "properties": { "total_alerts": { "type": "integer" } } } } } } } } } } }, "/api/v1/peer-benchmark/{ticker}": { "get": { "operationId": "getPeerBenchmark", "summary": "Peer Benchmark", "description": "Auto-generated peer group by sector, market cap band, and exchange with 7-metric benchmark comparison.", "tags": [ "Valuation" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker" } ], "responses": { "200": { "description": "Peer benchmark", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/pep-check/{slug}": { "get": { "tags": [ "Compliance" ], "summary": "PEP (Politically Exposed Person) Screening", "description": "Screen a person for PEP status based on FATF R12 criteria adapted for GCC markets. Checks ruling family membership, SWF representation, government appointments, regulatory positions, merchant family connections.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Person slug (URL-safe name)" } ], "responses": { "200": { "description": "PEP screening result with categories, risk level, reasons, and associated entities" }, "404": { "description": "Person not found" } } } }, "/api/v1/portfolio": { "get": { "operationId": "listPortfolios", "summary": "List Portfolios", "description": "List all portfolios for the authenticated API key.", "tags": [ "Portfolio" ], "responses": { "200": { "description": "Portfolio list", "content": { "application/json": { "schema": { "type": "object", "properties": { "portfolios": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "operationId": "createPortfolio", "summary": "Create Portfolio", "description": "Create a new portfolio with name, description, and base currency.", "tags": [ "Portfolio" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "base_currency": { "type": "string", "enum": [ "USD", "AED", "SAR", "QAR", "BHD", "OMR", "KWD", "JOD", "TRY" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Portfolio created" } } }, "delete": { "operationId": "deletePortfolio", "summary": "Delete Portfolio", "description": "Delete a portfolio by ID.", "tags": [ "Portfolio" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portfolio deleted" } } } }, "/api/v1/portfolio/holdings": { "get": { "operationId": "listHoldings", "summary": "List Holdings", "description": "List holdings for a portfolio.", "tags": [ "Portfolio" ], "parameters": [ { "name": "portfolio_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Holdings list", "content": { "application/json": { "schema": { "type": "object", "properties": { "holdings": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "operationId": "addHolding", "summary": "Add Holding", "description": "Add a single holding or bulk import via CSV.", "tags": [ "Portfolio" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "portfolio_id": { "type": "string" }, "ticker": { "type": "string" }, "quantity": { "type": "number" }, "cost_basis": { "type": "number" }, "currency": { "type": "string" } } } } } }, "responses": { "201": { "description": "Holding added" } } } }, "/api/v1/portfolio/shariah": { "get": { "operationId": "getPortfolioShariah", "summary": "Portfolio Shariah Overlay", "description": "Get AAOIFI Shariah compliance overlay for portfolio holdings \u2014 compliant/non-compliant/watch status per holding.", "tags": [ "Portfolio", "Islamic Finance" ], "parameters": [ { "name": "portfolio_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shariah overlay", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/portfolio/zakat": { "get": { "operationId": "getPortfolioZakat", "summary": "Portfolio Zakat Calculation", "description": "Calculate zakat obligation (AAOIFI FAS 9: 2.5% of qualifying wealth) with per-holding breakdown.", "tags": [ "Portfolio", "Islamic Finance" ], "parameters": [ { "name": "portfolio_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Zakat calculation", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/regulatory-actions": { "get": { "operationId": "getRegulatoryRisk", "summary": "Regulatory Risk Analysis", "description": "Market-wide regulatory enforcement analysis: penalty totals, regulator summaries, action type breakdown, repeat offender detection, risk scoring 0-100.", "tags": [ "Risk" ], "responses": { "200": { "description": "Regulatory risk analysis across all companies" } } } }, "/api/v1/regulatory-actions/{ticker}": { "get": { "operationId": "getRegulatoryRiskForTicker", "summary": "Company Regulatory Risk", "description": "Regulatory enforcement history and risk score for a specific company. Includes penalties, action types, and repeat offender status.", "tags": [ "Risk" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Company regulatory risk details" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/research-briefing/{slug}": { "get": { "summary": "Research briefing", "description": "Structured research briefing with change detection diff engine. Identifies key changes since last briefing.", "operationId": "getResearchBriefing", "tags": [ "IR & Analyst" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "emaar-properties" } ], "responses": { "200": { "description": "Research briefing", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/screen-portfolio": { "post": { "operationId": "screenPortfolio", "summary": "Screen Portfolio", "description": "Batch Shariah + governance + Zakat screening for up to 50 tickers. Returns per-holding compliance status and portfolio-level zakat estimate.", "tags": [ "Portfolio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tickers" ], "properties": { "tickers": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "Ticker symbols to screen" }, "weights": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Portfolio weights by ticker (0-1)" } } } } } }, "responses": { "200": { "description": "Portfolio screening results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortfolioScreen" } } } } } } } } }, "/api/v1/screener": { "get": { "operationId": "screener", "summary": "Stock Screener", "description": "Query the denormalized screener view with filters, sorting, and market cap ranges. Returns all 212+ columns from v_screener.", "tags": [ "Screener" ], "parameters": [ { "name": "sector", "in": "query", "schema": { "type": "string" }, "description": "Filter by GICS sector" }, { "name": "exchange", "in": "query", "schema": { "type": "string" }, "description": "Filter by exchange code (DFM, ADX, ASE, BK, QSE, MSX, BHB, TDWL, BIST, ISX)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "market_cap_usd" }, "description": "Column to sort by" }, { "name": "dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction" }, { "name": "min_mcap", "in": "query", "schema": { "type": "integer" }, "description": "Minimum market cap in USD" }, { "name": "max_mcap", "in": "query", "schema": { "type": "integer" }, "description": "Maximum market cap in USD" } ], "responses": { "200": { "description": "Screener results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "columns": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/v1/short-interest/{ticker}": { "get": { "operationId": "getShortInterest", "summary": "Short Interest Data", "description": "Net short positions reported by Edaa (Saudi Securities Depository Center). Includes % of outstanding, % of free float, days to cover, and securities lending data.", "tags": [ "Market Signals" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "Short interest data sorted by report date descending", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "report_date": { "type": "string", "format": "date" }, "short_shares": { "type": "integer", "nullable": true }, "short_pct_outstanding": { "type": "number", "nullable": true }, "short_pct_float": { "type": "number", "nullable": true }, "days_to_cover": { "type": "number", "nullable": true }, "avg_daily_volume": { "type": "integer", "nullable": true }, "shares_outstanding": { "type": "integer", "nullable": true }, "free_float_shares": { "type": "integer", "nullable": true }, "slb_shares_lent": { "type": "integer", "nullable": true }, "slb_shares_borrowed": { "type": "integer", "nullable": true }, "slb_lending_fee_pct": { "type": "number", "nullable": true }, "source": { "type": "string" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/social-sentiment/{ticker}": { "get": { "summary": "Social sentiment for a company", "description": "Combined news + social media sentiment analysis. Aggregates sentiment from news articles, announcements, and social posts (Arabic + English).", "operationId": "getSocialSentiment", "tags": [ "Social" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "EMAAR" } ], "responses": { "200": { "description": "Social sentiment data", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sukuk-instruments": { "get": { "operationId": "getSukukInstruments", "summary": "Sukuk Instruments", "description": "Islamic bond (sukuk) analytics. 114 instruments across sovereign and corporate issuers with Shariah structure, ratings, and maturity data.", "tags": [ "Islamic Finance" ], "parameters": [ { "name": "ticker", "in": "query", "schema": { "type": "string" }, "description": "Filter by issuer ticker" }, { "name": "structure", "in": "query", "schema": { "type": "string", "enum": [ "ijara", "murabaha", "wakala", "mudaraba", "musharaka", "hybrid", "other" ] }, "description": "Filter by Shariah structure" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "outstanding", "all" ], "default": "outstanding" }, "description": "Filter by instrument status" } ], "responses": { "200": { "description": "Sukuk instrument list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/SukukInstrument" } }, "count": { "type": "integer" }, "total_outstanding_usd_m": { "type": "number" }, "sovereign_count": { "type": "integer" }, "green_count": { "type": "integer" } } } } } } } } } } }, "/api/v1/technical-signals/{ticker}": { "get": { "summary": "Technical signals", "description": "RSI, MACD, SMA crossovers, Bollinger Bands, volume analysis. Pure price/volume technical indicators.", "operationId": "getTechnicalSignals", "tags": [ "Signals" ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ARAMCO" } ], "responses": { "200": { "description": "Technical signals", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/ubo/{ticker}": { "get": { "tags": [ "Compliance" ], "summary": "Ultimate Beneficial Ownership Analysis", "description": "Trace ownership chains through nominees, custodians, and holding companies to identify true beneficial owners.", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" } ], "responses": { "200": { "description": "UBO analysis with ownership chains, beneficial owners, transparency rating, and risk score" }, "404": { "description": "Company not found" } } } }, "/api/v1/widgets": { "get": { "operationId": "getWidgets", "summary": "Widget Data", "description": "Lightweight JSON for embeddable widgets (Shariah, governance, zakat). CORS-enabled.", "tags": [ "Embeds" ], "security": [], "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Company ticker symbol" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "shariah", "governance", "zakat" ] }, "description": "Widget type" } ], "responses": { "200": { "description": "Widget data", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key from your SouqData account dashboard" } }, "responses": { "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "schemas": { "CompanySummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ticker": { "type": "string" }, "company_name": { "type": "string" }, "company_name_ar": { "type": "string" }, "gics_sector": { "type": "string" }, "gics_industry_group": { "type": "string" }, "exchange_code": { "type": "string" }, "market_cap_usd": { "type": "number" }, "is_shariah_compliant": { "type": "boolean" }, "reporting_currency": { "type": "string" } } }, "CompanyDetail": { "type": "object", "properties": { "issuer": { "$ref": "#/components/schemas/CompanySummary" }, "directors": { "type": "array", "items": { "$ref": "#/components/schemas/Director" } }, "financials": { "type": "array", "items": { "type": "object" } }, "dividends": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "array", "items": { "type": "object" } } } }, "Director": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "full_name_ar": { "type": "string" }, "gender": { "type": "string" }, "nationality": { "type": "string" }, "biography": { "type": "string" }, "education": { "type": "string" }, "role": { "type": "string" }, "is_independent": { "type": "boolean" }, "is_chair": { "type": "boolean" }, "is_current": { "type": "boolean" } } }, "Officer": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "board", "executive" ], "description": "Derived from is_board_role column. 'board' = board member, 'executive' = management only." }, "role": { "type": "string" }, "status": { "type": "string", "enum": [ "Current", "Former" ], "description": "Appointment status. Use this instead of is_current." }, "is_current": { "type": "boolean", "description": "Deprecated \u2014 use status field instead." }, "is_board_role": { "type": "boolean", "description": "True if this is a board appointment (director, chairman, independent, etc.)." }, "appointed_date": { "type": "string", "format": "date", "nullable": true }, "departed_date": { "type": "string", "format": "date", "nullable": true }, "gender": { "type": "string", "nullable": true, "description": "Gender of the officer (e.g. 'Male', 'Female')." }, "is_independent": { "type": "boolean", "nullable": true }, "permanent_id": { "type": "string", "nullable": true } } }, "FairValue": { "type": "object", "properties": { "ticker": { "type": "string" }, "current_price": { "type": "number" }, "currency": { "type": "string" }, "consensus_fair_value": { "type": "number" }, "upside_pct": { "type": "number" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "insufficient" ] }, "models": { "type": "object", "properties": { "dcf": { "type": "object", "properties": { "value": { "type": "number" }, "confidence": { "type": "string" } } }, "ddm": { "type": "object", "properties": { "value": { "type": "number" }, "confidence": { "type": "string" } } }, "ev_ebitda": { "type": "object", "properties": { "value": { "type": "number" }, "confidence": { "type": "string" } } } } } } }, "AccountingQuality": { "type": "object", "properties": { "ticker": { "type": "string" }, "m_score": { "type": "number" }, "m_score_flag": { "type": "string", "enum": [ "clean", "caution", "manipulator" ] }, "accruals_ratio": { "type": "number" }, "composite_score": { "type": "integer" }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] } } }, "FinancialDistress": { "type": "object", "properties": { "ticker": { "type": "string" }, "altman_z": { "type": "number", "nullable": true }, "altman_z_zone": { "type": "string", "enum": [ "safe", "grey", "distress" ] }, "altman_z_adjusted": { "type": "number", "nullable": true }, "piotroski_f": { "type": "integer", "nullable": true }, "piotroski_grade": { "type": "string" } } }, "DividendSafety": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "score": { "type": "integer" }, "grade": { "type": "string" }, "is_reit": { "type": "boolean" }, "dividend_yield_pct": { "type": "number" }, "dps_local": { "type": "number" }, "payout_ratio_pct": { "type": "number" }, "streak_years": { "type": "integer" }, "components": { "type": "object" } } }, "BoardSuccession": { "type": "object", "properties": { "ticker": { "type": "string" }, "succession_risk": { "type": "number" }, "board_size": { "type": "integer" }, "avg_tenure_years": { "type": "number" }, "members_retiring_3y": { "type": "array", "items": { "type": "object" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "BoardCertification": { "type": "object", "properties": { "director_id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "qualification": { "type": "string" }, "classification": { "type": "string" }, "certification_body": { "type": "string" }, "certification_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "is_mandatory": { "type": "boolean" }, "country": { "type": "string" } } }, "CMAGovernance": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "compliance_score": { "type": "number" }, "articles_compliant": { "type": "array", "items": { "type": "object" } }, "articles_non_compliant": { "type": "array", "items": { "type": "object" } }, "articles_na": { "type": "array", "items": { "type": "object" } } } }, "SukukInstrument": { "type": "object", "properties": { "ticker": { "type": "string", "nullable": true }, "issuer_name": { "type": "string" }, "sukuk_name": { "type": "string" }, "currency": { "type": "string" }, "amount_issued": { "type": "number", "description": "In millions" }, "amount_outstanding": { "type": "number", "nullable": true }, "issue_date": { "type": "string", "format": "date" }, "maturity_date": { "type": "string", "format": "date" }, "coupon_rate": { "type": "number" }, "yield_to_maturity": { "type": "number" }, "shariah_structure": { "type": "string", "enum": [ "ijara", "murabaha", "wakala", "mudaraba", "musharaka", "hybrid", "other" ] }, "is_sovereign": { "type": "boolean" }, "is_green_sukuk": { "type": "boolean" }, "credit_rating": { "type": "string" }, "status": { "type": "string" } } }, "NationalizationCompliance": { "type": "object", "properties": { "ticker": { "type": "string" }, "records": { "type": "array", "items": { "type": "object" } }, "latest": { "type": "object" }, "years_tracked": { "type": "integer" } } }, "DealInsiderSignals": { "type": "object", "properties": { "ticker": { "type": "string" }, "period_days": { "type": "integer" }, "insider_activity_score": { "type": "number" }, "pre_deal_patterns": { "type": "array", "items": { "type": "object" } }, "volume_anomalies": { "type": "array", "items": { "type": "object" } } } }, "GigaProjectExposure": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "total_exposure_pct": { "type": "number", "description": "Total contract value as % of market cap" }, "contract_count": { "type": "integer" }, "total_contract_value_usd_m": { "type": "number" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "project_name": { "type": "string" }, "contract_value_usd_m": { "type": "number" }, "role": { "type": "string" }, "award_date": { "type": "string", "format": "date" }, "status": { "type": "string" } } } }, "exposure_grade": { "type": "string", "enum": [ "High", "Medium", "Low", "None" ] } } }, "DegreesOfSeparation": { "type": "object", "properties": { "from": { "type": "string", "format": "uuid" }, "to": { "type": "string", "format": "uuid" }, "connected": { "type": "boolean" }, "degrees": { "type": "integer" }, "path": { "type": "array", "items": { "type": "object" } }, "shared_companies": { "type": "array", "items": { "type": "string" } } } }, "InvestorQA": { "type": "object", "properties": { "ticker": { "type": "string" }, "company_name": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "difficulty": { "type": "integer" }, "question": { "type": "string" }, "answer_hint": { "type": "string" } } } } } }, "IRRehearsal": { "type": "object", "properties": { "language_risks": { "type": "array", "items": { "type": "object" } }, "sentiment_score": { "type": "number" }, "media_pickup_potential": { "type": "number" }, "readability": { "type": "object" }, "buzzword_analysis": { "type": "array", "items": { "type": "object" } } } }, "PortfolioScreen": { "type": "object", "properties": { "portfolio": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "shariah_compliant": { "type": "boolean" }, "governance_grade": { "type": "string" }, "zakat_estimate": { "type": "number" }, "weight": { "type": "number" } } } }, "portfolio_zakat_annual": { "type": "number" } } } } } }