{"openapi":"3.1.0","info":{"title":"ShariahAPI","version":"1.0.0","description":"Shariah compliance and screening infrastructure for financial assets. Provides rule-based decisioning, explainable pass/fail output, purification guidance, and confidence scoring based on AAOIFI and SC Malaysia standards.","contact":{"name":"ShariahAPI Support","email":"api@shariahapi.com"},"license":{"name":"MIT"}},"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Use `Authorization: Bearer <api_key>`"},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Use `X-API-Key: <api_key>`"}},"schemas":{"AssetFinancials":{"type":"object","required":["totalAssets","totalDebt","cashAndEquivalents","totalRevenue","nonHalalRevenue"],"properties":{"totalAssets":{"type":"number","description":"Total assets in USD"},"totalDebt":{"type":"number","description":"Total debt (interest-bearing)"},"cashAndEquivalents":{"type":"number","description":"Cash and cash equivalents"},"totalRevenue":{"type":"number","description":"Total annual revenue"},"nonHalalRevenue":{"type":"number","description":"Revenue from non-halal sources (alcohol, interest, etc.)"},"accountsReceivable":{"type":"number","description":"Accounts receivable"},"interestIncome":{"type":"number","description":"Interest income"},"interestExpense":{"type":"number","description":"Interest expense"},"marketCap":{"type":"number","description":"Market capitalisation"},"fiscalYear":{"type":"number","description":"Fiscal year (e.g. 2024)"}}},"ReasonCode":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code (e.g. DEBT_FAIL)"},"rule":{"type":"string","description":"Rule name"},"description":{"type":"string","description":"Human-readable explanation"},"severity":{"type":"string","enum":["FAIL","WARNING","INFO"]},"value":{"type":"number","description":"Actual value (%)"},"threshold":{"type":"number","description":"Allowed threshold (%)"},"passed":{"type":"boolean"}}},"PurificationGuidance":{"type":"object","properties":{"required":{"type":"boolean"},"percentage":{"type":"number","description":"Percentage of returns to purify"},"amount":{"type":"number","description":"Absolute amount (same currency as financials)"},"basis":{"type":"string"},"instructions":{"type":"array","items":{"type":"string"}}}},"ScreeningResult":{"type":"object","properties":{"assetId":{"type":"string"},"symbol":{"type":"string"},"status":{"type":"string","enum":["COMPLIANT","NON_COMPLIANT","DOUBTFUL","NOT_RATED"]},"compliant":{"type":"boolean"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Compliance score 0–100"},"screenedAt":{"type":"string","format":"date-time"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"purification":{"$ref":"#/components/schemas/PurificationGuidance"},"summary":{"type":"string"},"methodology":{"type":"string","enum":["AAOIFI","SC_MALAYSIA","CUSTOM"]},"version":{"type":"string"}}},"ComplianceChange":{"type":"object","properties":{"id":{"type":"string"},"assetId":{"type":"string"},"symbol":{"type":"string"},"changedAt":{"type":"string","format":"date-time"},"previousStatus":{"type":"string"},"newStatus":{"type":"string"},"changedRules":{"type":"array","items":{"type":"string"}},"triggeredBy":{"type":"string"},"notes":{"type":"string"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Full key shown only at creation"},"name":{"type":"string"},"tenantId":{"type":"string"},"plan":{"type":"string","enum":["FREE","STARTER","PROFESSIONAL","ENTERPRISE"]},"rateLimit":{"type":"number","description":"Requests per hour"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time"},"isActive":{"type":"boolean"}}},"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"version":{"type":"string"},"processingTimeMs":{"type":"number"}}}}}}},"paths":{"/screen":{"post":{"summary":"Screen an asset for Shariah compliance","operationId":"screenAsset","tags":["Screening"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset"],"properties":{"asset":{"type":"object","required":["symbol","financials"],"properties":{"id":{"type":"string"},"symbol":{"type":"string","example":"AAPL"},"name":{"type":"string","example":"Apple Inc."},"sector":{"type":"string","example":"Technology"},"businessActivities":{"type":"array","items":{"type":"string"},"example":["smartphones","software","services"]},"financials":{"$ref":"#/components/schemas/AssetFinancials"}}},"methodology":{"type":"string","enum":["AAOIFI","SC_MALAYSIA","CUSTOM"],"default":"AAOIFI"}}},"example":{"asset":{"symbol":"AAPL","name":"Apple Inc.","sector":"Technology","businessActivities":["smartphones","software","digital services"],"financials":{"totalAssets":352583000000,"totalDebt":111088000000,"cashAndEquivalents":29965000000,"totalRevenue":383285000000,"nonHalalRevenue":0,"accountsReceivable":29508000000,"interestIncome":3750000000,"fiscalYear":2023}},"methodology":"AAOIFI"}}}},"responses":{"200":{"description":"Screening complete","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"properties":{"data":{"$ref":"#/components/schemas/ScreeningResult"}}}]}}}},"401":{"description":"Unauthorized — missing or invalid API key"},"422":{"description":"Validation error"}}}},"/asset/{id}":{"get":{"summary":"Get latest screening result for an asset","operationId":"getAsset","tags":["Assets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"history","in":"query","schema":{"type":"boolean"},"description":"Set true to get full screening history"}],"responses":{"200":{"description":"Screening result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"properties":{"data":{"$ref":"#/components/schemas/ScreeningResult"}}}]}}}},"404":{"description":"Asset not found"}}}},"/compliance-history":{"get":{"summary":"Get compliance change events","operationId":"getComplianceHistory","tags":["History"],"parameters":[{"name":"assetId","in":"query","schema":{"type":"string"},"description":"Filter by asset ID"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"List of compliance changes","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceChange"}}}}]}}}}}}},"/keys":{"post":{"summary":"Create a new API key","operationId":"createApiKey","tags":["API Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Production Key"},"plan":{"type":"string","enum":["FREE","STARTER","PROFESSIONAL","ENTERPRISE"],"default":"FREE"}}}}}},"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"properties":{"data":{"$ref":"#/components/schemas/ApiKey"}}}]}}}}}},"get":{"summary":"List API keys for current tenant","operationId":"listApiKeys","tags":["API Keys"],"responses":{"200":{"description":"List of API keys (secrets masked)"}}}}},"tags":[{"name":"Screening","description":"Core compliance screening endpoints"},{"name":"Assets","description":"Asset result retrieval"},{"name":"History","description":"Compliance change tracking"},{"name":"API Keys","description":"API key management"}]}