{"openapi":"3.1.0","info":{"title":"Halal Terminal API","description":"The **Halal Terminal API** is the most comprehensive Islamic finance data\nplatform available â€” 58+ REST endpoints, 22 MCP tools, and 7 AI resources\nacross 15 categories covering Shariah screening, market data, portfolio\ncompliance, ETF analysis, news, SEC filings, dividends, zakat calculators,\nand more. Connect via REST API or MCP (Model Context Protocol) for AI-native access.\n\n---\n\n## Quick start\n\n**1. Get a free API key** â€” no credit card required:\n\n```bash\ncurl -X POST https://api.halalterminal.com/api/keys/generate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\"}'\n```\n\n**2. Screen your first stock:**\n\n```bash\ncurl https://api.halalterminal.com/api/screen?symbol=AAPL \\\n -H \"X-API-Key: YOUR_KEY\"\n```\n\n**3. Parse the response:**\n\n```json\n{\n \"symbol\": \"AAPL\",\n \"is_compliant\": true,\n \"compliance_status\": \"COMPLIANT\",\n \"revenue_breakdown\": { ... },\n \"financial_ratios\": { ... }\n}\n```\n\nThat's it â€” you're screening.\n\n---\n\n## Authentication\n\nEvery `/api/*` request must include your key in the `X-API-Key` header.\n\n**Exempt endpoints** (no key required): `GET /api/health`,\n`POST /api/keys/*`, `POST /api/billing/*`.\n\n### Code examples\n\n**Python**\n```python\nimport requests\n\nheaders = {\"X-API-Key\": \"YOUR_KEY\"}\nr = requests.get(\n \"https://api.halalterminal.com/api/screen\",\n params={\"symbol\": \"AAPL\"},\n headers=headers,\n)\nprint(r.json())\n```\n\n**JavaScript (fetch)**\n```javascript\nconst res = await fetch(\n \"https://api.halalterminal.com/api/screen?symbol=AAPL\",\n { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await res.json();\n```\n\n---\n\n## Plans & token-based pricing\n\n| Plan | Tokens / month | Price | Overage |\n|------|---------------:|------:|---------|\n| **Free** | 50 | $0 | Hard block |\n| **Starter** | 2,500 | $19/mo | $0.01/token |\n| **Pro** | 15,000 | $49/mo | $0.008/token |\n| **Enterprise** | Unlimited | $199/mo | N/A |\n\nEach API request costs a certain number of **tokens** depending on the\nendpoint. Lightweight reads (database search, news) cost **1 token**,\nstandard reads (quotes, OHLC) cost **2 tokens**, screening and heavy\noperations cost **5â€“50 tokens**. Free endpoints (health, education,\napi-keys, billing) cost **0 tokens**.\n\nSee the full cost table at [`GET /api/keys/token-costs`](/api/keys/token-costs).\n\n**Overage**: Free plan hard-blocks at the limit. Paid plans continue\nat the per-token overage rate â€” you're never locked out. Token usage\nresets monthly.\n\nUpgrade anytime via the [billing endpoint](/api/billing/checkout).\n\n---\n\n## Common recipes\n\n| Use case | Endpoint | Method |\n|----------|----------|--------|\n| Screen a single stock | `/api/screen?symbol=AAPL` | GET |\n| Bulk-screen an index | `/api/screen-bulk` | POST |\n| Get real-time quote | `/api/quote/{symbol}` | GET |\n| Check portfolio compliance | `/api/portfolio/scan` | POST |\n| Screen an ETF's holdings | `/api/etf/{symbol}/screening` | GET |\n| Calculate zakat | `/api/zakat/calculate` | POST |\n| Calculate dividend purification | `/api/dividends/{symbol}/purification` | GET |\n| Search the stock database | `/api/database/search?q=apple` | GET |\n| Get market news | `/api/news/market` | GET |\n| Fetch SEC filings | `/api/filings/{symbol}` | GET |\n\n---\n\n## Error handling\n\nAll errors return a consistent JSON envelope:\n\n```json\n{\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human-readable explanation\",\n \"detail\": null\n}\n```\n\n| Status | Code | Meaning |\n|--------|------|---------|\n| 400 | `HTTP_400` | Bad request â€” check parameters |\n| 401 | `API_KEY_REQUIRED` | Missing `X-API-Key` header |\n| 401 | `INVALID_API_KEY` | Key does not exist |\n| 403 | `API_KEY_DEACTIVATED` | Key has been disabled |\n| 404 | `HTTP_404` | Resource not found |\n| 429 | `QUOTA_EXCEEDED` | Monthly quota exhausted â€” upgrade plan |\n| 500 | `INTERNAL_ERROR` | Server error â€” retry or contact support |\n\n---\n\n## Rate limits & headers\n\nEvery authenticated response includes:\n\n| Header | Description |\n|--------|-------------|\n| `X-Request-ID` | Unique request identifier for debugging |\n| `X-Tokens-Charged` | Number of tokens deducted for this request |\n| `X-Tokens-Remaining` | Tokens remaining in the current billing period (-1 = unlimited) |\n| `X-Tokens-Overage` | Present and set to `true` when the request exceeded the plan allowance |\n\nWhen you hit your quota the `429` response includes your current\n`plan`, `tokens_limit`, and `tokens_used` in the `detail` field.\n\n---\n","version":"1.0.0"},"paths":{"/api/health":{"get":{"tags":["health"],"summary":"Health Check","description":"Check API health status.\n\nReturns a simple status message confirming the API is running.\nThis endpoint requires no authentication and is suitable for\nuptime monitors and load-balancer health probes.\n\n**curl example**:\n```bash\ncurl https://api.halalterminal.com/api/health\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\"https://api.halalterminal.com/api/health\")\nprint(resp.json()[\"message\"])\n```","operationId":"health_check_api_health_get","responses":{"200":{"description":"API health status message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}},"security":[]}},"/api/screen-bulk/indices":{"get":{"tags":["screening"],"summary":"List Indices","description":"List available stock indices for bulk screening.\n\nReturns every index supported by the bulk-screening engine, along with\nan estimated ticker count and a short description.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/indices\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/indices\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"list_indices_api_screen_bulk_indices_get","responses":{"200":{"description":"List of available stock indices with metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndicesResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"}}}},"/api/screen-bulk/status":{"get":{"tags":["screening"],"summary":"Bulk Status","description":"Get the status of a bulk screening run.\n\nReturns real-time progress for the active run (or a specific run if\n`run_id` is provided), including completion percentage, current symbol\nbeing processed, and estimated time remaining.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/status?run_id=abc123\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/status\",\n params={\"run_id\": \"abc123\"},\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"bulk_status_api_screen_bulk_status_get","parameters":[{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}}],"responses":{"200":{"description":"Current status of the active or most recent bulk screening run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/runs":{"get":{"tags":["screening"],"summary":"List Runs","description":"List historical bulk screening runs.\n\nReturns a paginated history of screening runs, optionally filtered by\nindex name (e.g. \"SP500\") or status (e.g. \"completed\", \"running\").\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/runs?index_name=SP500&page=1&page_size=10\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/runs\",\n params={\"index_name\": \"SP500\", \"page\": 1, \"page_size\": 10},\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"list_runs_api_screen_bulk_runs_get","parameters":[{"name":"index_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Name"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Paginated list of past and current screening runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunHistoryResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/compare":{"get":{"tags":["screening"],"summary":"Compare Runs","description":"Compare the results of two bulk screening runs.\n\nIdentifies symbols whose compliance status changed between run A and\nrun B, including newly compliant, newly non-compliant, added, and\nremoved symbols.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/compare?run_a=abc123&run_b=def456\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/compare\",\n params={\"run_a\": \"abc123\", \"run_b\": \"def456\"},\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"compare_runs_api_screen_bulk_compare_get","parameters":[{"name":"run_a","in":"query","required":true,"schema":{"type":"string","title":"Run A"}},{"name":"run_b","in":"query","required":true,"schema":{"type":"string","title":"Run B"}}],"responses":{"200":{"description":"Side-by-side comparison of two screening runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/backend__schemas__screening__CompareResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk":{"post":{"tags":["screening"],"summary":"Screen Bulk","description":"Trigger a new bulk Shariah screening run.\n\nStarts asynchronous screening of all tickers in the specified index\n(e.g. \"SP500\", \"DJIA\"). Returns immediately with a run ID that can be\nused to poll status, fetch results, or cancel the run.\n\n**curl example:**\n```bash\ncurl -X POST \"https://api.example.com/api/screen-bulk\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"index_name\": \"SP500\", \"limit\": 50, \"force_refresh\": false}'\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.example.com/api/screen-bulk\",\n headers={\"Authorization\": \"Bearer \"},\n json={\"index_name\": \"SP500\", \"limit\": 50, \"force_refresh\": False},\n)\nprint(resp.json())\n```","operationId":"screen_bulk_api_screen_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkScreenRequest"}}},"required":true},"responses":{"202":{"description":"Bulk screening run accepted and queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkScreenResponse"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}/cancel":{"post":{"tags":["screening"],"summary":"Cancel Run","description":"Cancel a running bulk screening job.\n\nStops the specified run gracefully. Results already collected are\npreserved and can still be queried. Returns the run status at the time\nof cancellation.\n\n**curl example:**\n```bash\ncurl -X POST \"https://api.example.com/api/screen-bulk/abc123/cancel\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.example.com/api/screen-bulk/abc123/cancel\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"cancel_run_api_screen_bulk__run_id__cancel_post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"Confirmation that the run has been cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelResponse"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}/results":{"get":{"tags":["screening"],"summary":"Get Run Results","description":"Retrieve filtered, paginated results for a bulk screening run.\n\nReturns individual symbol screening results for the given run. Supports\nfiltering by compliance status, methodology (e.g. \"aaoifi\", \"djim\"),\nsector, and error state, plus sorting and pagination.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/abc123/results?compliant=true&methodology=aaoifi&page=1&page_size=20\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/abc123/results\",\n params={\"compliant\": True, \"methodology\": \"aaoifi\", \"page\": 1},\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"get_run_results_api_screen_bulk__run_id__results_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}},{"name":"compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Compliant"}},{"name":"methodology","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Methodology"}},{"name":"sector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"}},{"name":"has_error","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Error"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","default":"asc","title":"Sort Order"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Paginated screening results for the specified run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResultsResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}/summary":{"get":{"tags":["screening"],"summary":"Get Run Summary","description":"Get an aggregated summary of a bulk screening run.\n\nReturns compliance statistics broken down by methodology and sector,\noverall compliance rate, and a list of the top compliant stocks.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/abc123/summary\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/abc123/summary\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"get_run_summary_api_screen_bulk__run_id__summary_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"Aggregated compliance summary for the screening run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSummaryResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}/export/csv":{"get":{"tags":["screening"],"summary":"Export Csv","description":"Export screening results as a CSV file.\n\nReturns a downloadable CSV containing every screened symbol, its\ncompliance status, financial ratios, and methodology-level verdicts.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/abc123/export/csv\" \\\n -H \"Authorization: Bearer \" \\\n -o screening_results.csv\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/abc123/export/csv\",\n headers={\"Authorization\": \"Bearer \"},\n)\nwith open(\"screening_results.csv\", \"w\") as f:\n f.write(resp.text)\n```","operationId":"export_csv_api_screen_bulk__run_id__export_csv_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"CSV file download of all screening results","content":{"application/json":{"schema":{}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}/export/json":{"get":{"tags":["screening"],"summary":"Export Json","description":"Export screening results as JSON.\n\nReturns the complete screening dataset for a run in JSON format,\nsuitable for programmatic consumption or archiving.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/screen-bulk/abc123/export/json\" \\\n -H \"Authorization: Bearer \" \\\n -o screening_results.json\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/screen-bulk/abc123/export/json\",\n headers={\"Authorization\": \"Bearer \"},\n)\ndata = resp.json()\n```","operationId":"export_json_api_screen_bulk__run_id__export_json_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"JSON export of all screening results","content":{"application/json":{"schema":{}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen-bulk/{run_id}":{"delete":{"tags":["screening"],"summary":"Delete Run","description":"Delete a bulk screening run and its results.\n\nPermanently removes a completed or cancelled run and all associated\nscreening results from the database. This action cannot be undone.\n\n**curl example:**\n```bash\ncurl -X DELETE \"https://api.example.com/api/screen-bulk/abc123\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.delete(\n \"https://api.example.com/api/screen-bulk/abc123\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"delete_run_api_screen_bulk__run_id__delete","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"Confirmation that the run was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRunResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/results/updates":{"get":{"tags":["screening"],"summary":"Get Results Updates","description":"Get screening results updated since a given timestamp.\n\nReturns only the results that have been created or modified after the\n`since` ISO-8601 timestamp. Useful for incremental polling by\nfront-end dashboards.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/results/updates?since=2025-01-15T00:00:00Z\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/results/updates\",\n params={\"since\": \"2025-01-15T00:00:00Z\"},\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"get_results_updates_api_results_updates_get","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","title":"Since"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}}],"responses":{"200":{"description":"List of screening results updated since the given timestamp","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningResultResponse"},"title":"Response Get Results Updates Api Results Updates Get"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/results":{"get":{"tags":["screening"],"summary":"Get Results","description":"Get all cached screening results.\n\nReturns every screening result currently stored in the database,\nregardless of when the screening was performed.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/results\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/results\",\n headers={\"Authorization\": \"Bearer \"},\n)\nresults = resp.json()\n```","operationId":"get_results_api_results_get","responses":{"200":{"description":"List of all cached screening results","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ScreeningResultResponse"},"type":"array","title":"Response Get Results Api Results Get"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"}}}},"/api/result/{symbol}":{"get":{"tags":["screening"],"summary":"Get Result","description":"Get the cached screening result for a single symbol.\n\nReturns the most recent Shariah compliance screening result for the\ngiven ticker symbol. Returns 404 if the symbol has not been screened.\n\n**curl example:**\n```bash\ncurl -X GET \"https://api.example.com/api/result/AAPL\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.example.com/api/result/AAPL\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"get_result_api_result__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Shariah compliance screening result for the requested symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningResultResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Resource or symbol not found"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screen/{symbol}":{"post":{"tags":["screening"],"summary":"Screen Symbol","description":"Screen a single symbol for Shariah compliance.\n\nPerforms a full Shariah compliance analysis on the given ticker,\nincluding business activity screening and financial ratio checks\nagainst AAOIFI, DJIM, FTSE, MSCI, and S&P methodologies.\n\n**curl example:**\n```bash\ncurl -X POST \"https://api.example.com/api/screen/AAPL\" \\\n -H \"Authorization: Bearer \"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.example.com/api/screen/AAPL\",\n headers={\"Authorization\": \"Bearer \"},\n)\nprint(resp.json())\n```","operationId":"screen_symbol_api_screen__symbol__post","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Freshly computed Shariah compliance screening result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningResultResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/suggest":{"get":{"tags":["database"],"summary":"Suggest Symbol","description":"Auto-complete symbol suggestions for a search query.\n\nReturns a ranked list of symbol suggestions that match the provided\nquery prefix, useful for type-ahead search interfaces.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/suggest?q=AAP\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\n \"http://localhost:8000/api/suggest\",\n params={\"q\": \"AAP\"},\n)\nsuggestions = resp.json()\n```","operationId":"suggest_symbol_api_suggest_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}}],"responses":{"200":{"description":"List of symbol suggestions matching the query","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SuggestionResponse"},"title":"Response Suggest Symbol Api Suggest Get"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/database/search":{"get":{"tags":["database"],"summary":"Search Database","description":"Search the local database of assets with filtering and pagination.\n\nReturns a paginated list of assets matching the query string and optional\nfilters for asset type, sector, country, and exchange.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/database/search?q=Apple&asset_type=equities&limit=10\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\n \"http://localhost:8000/api/database/search\",\n params={\"q\": \"Apple\", \"asset_type\": \"equities\", \"limit\": 10},\n)\nresults = resp.json()\n```","operationId":"search_database_api_database_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"asset_type","in":"query","required":false,"schema":{"type":"string","default":"equities","title":"Asset Type"}},{"name":"sector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"}},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},{"name":"exchange","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Paginated search results with total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseSearchResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/database/stock/{symbol}":{"get":{"tags":["database"],"summary":"Get Stock From Database","description":"Retrieve the database record for a single stock by symbol.\n\nReturns the stored reference data for the given symbol including name,\nsector, exchange, and country.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/database/stock/AAPL\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/database/stock/AAPL\")\nstock = resp.json()\n```","operationId":"get_stock_from_database_api_database_stock__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Full database record for the requested symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseStockResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Symbol not found in database"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/database/stats":{"get":{"tags":["database"],"summary":"Get Database Stats","description":"Get aggregate statistics about the database contents.\n\nReturns counts of equities, ETFs, funds, indices, and screening results,\nalong with the number of distinct sectors and countries for equities.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/database/stats\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/database/stats\")\nstats = resp.json()\n```","operationId":"get_database_stats_api_database_stats_get","responses":{"200":{"description":"Aggregate statistics across all asset categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseStatsResponse"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"}}}},"/api/ohlc/{symbol}":{"get":{"tags":["market"],"summary":"Get Ohlc","description":"Retrieve OHLC candlestick data for a given symbol.\n\nReturns a time-series list of Open, High, Low, Close, and Volume data\npoints for the requested symbol, period, and interval.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/ohlc/AAPL?period=1y&interval=1d\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\n \"http://localhost:8000/api/ohlc/AAPL\",\n params={\"period\": \"1y\", \"interval\": \"1d\"},\n)\ncandles = resp.json()\n```","operationId":"get_ohlc_api_ohlc__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","default":"1y","title":"Period"}},{"name":"interval","in":"query","required":false,"schema":{"type":"string","default":"1d","title":"Interval"}}],"responses":{"200":{"description":"List of OHLC candlestick data points","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OHLCPointResponse"},"title":"Response Get Ohlc Api Ohlc Symbol Get"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Symbol not found in database"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/quote/{symbol}":{"get":{"tags":["market"],"summary":"Get Quote","description":"Get a real-time quote for a single symbol.\n\nReturns the latest price, change, volume, and key metrics for the\nrequested ticker symbol.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/quote/AAPL\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/quote/AAPL\")\nquote = resp.json()\n```","operationId":"get_quote_api_quote__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Real-time quote for the requested symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Symbol not found in database"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/quotes/batch":{"post":{"tags":["market"],"summary":"Get Quotes Batch","description":"Fetch quotes for multiple symbols in a single request.\n\nReturns a dictionary keyed by symbol, where each value is either the\nquote object or null if the symbol could not be resolved.\n\n**curl example**:\n```bash\ncurl -X POST \"http://localhost:8000/api/quotes/batch\" -H \"Content-Type: application/json\" -d '{\"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"]}'\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/quotes/batch\",\n json={\"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"]},\n)\nquotes = resp.json()\n```","operationId":"get_quotes_batch_api_quotes_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQuoteRequest"}}},"required":true},"responses":{"200":{"description":"Mapping of each requested symbol to its quote (or null if unavailable)","content":{"application/json":{"schema":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/QuoteResponse"},{"type":"null"}]},"type":"object","title":"Response Get Quotes Batch Api Quotes Batch Post"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/asset/{symbol}/full":{"get":{"tags":["market"],"summary":"Get Asset Full","description":"Get a comprehensive view of an asset combining multiple data sources.\n\nReturns a unified response containing the live quote, Shariah screening\nresult, and static database record for the given symbol.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/asset/AAPL/full\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/asset/AAPL/full\")\nasset = resp.json()\n```","operationId":"get_asset_full_api_asset__symbol__full_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Aggregated asset view with quote, screening, and database data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFullResponse"}}}},"401":{"description":"API key required or invalid"},"404":{"description":"Symbol not found in database"},"429":{"description":"Quota exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/trending":{"get":{"tags":["market"],"summary":"Get Trending","description":"List currently trending assets.\n\nReturns an ordered list of assets that are currently trending by\ntrading activity or price movement.\n\n**curl example**:\n```bash\ncurl -X GET \"http://localhost:8000/api/trending\"\n```\n\n**Python requests example**:\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/trending\")\ntrending = resp.json()\n```","operationId":"get_trending_api_trending_get","responses":{"200":{"description":"List of currently trending assets","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TrendingItemResponse"},"type":"array","title":"Response Get Trending Api Trending Get"}}}},"401":{"description":"API key required or invalid"},"429":{"description":"Quota exceeded"}}}},"/api/portfolio/scan":{"post":{"tags":["portfolio"],"summary":"Portfolio Scan","description":"Scan a portfolio of stocks for Shariah compliance.\n\nSet `force_refresh=true` to bypass cached screening data â€” available\nonly for enterprise and internal plans. For other plans the flag is\nsilently treated as False.","operationId":"portfolio_scan_api_portfolio_scan_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioScanRequest"}}},"required":true},"responses":{"200":{"description":"Per-symbol screening results and aggregate portfolio compliance summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioScanResponse"}}}},"429":{"description":"Rate limit exceeded. Try again later."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/watchlists":{"get":{"tags":["watchlists"],"summary":"List Watchlists","description":"List all watchlists.\n\nReturns every watchlist owned by the authenticated user, ordered by\ncreation date.\n\n**curl example**:\n```bash\ncurl https://api.halalterminal.com/api/watchlists \\\n -H \"X-API-Key: sk_live_abc123def456\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.halalterminal.com/api/watchlists\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n)\nwatchlists = resp.json()\n```","operationId":"list_watchlists_api_watchlists_get","responses":{"200":{"description":"All watchlists for the authenticated user","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/WatchlistResponse"},"type":"array","title":"Response List Watchlists Api Watchlists Get"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"}}},"post":{"tags":["watchlists"],"summary":"Create Watchlist","description":"Create a new watchlist.\n\nCreates a named watchlist with an optional initial set of symbols.\nReturns the full watchlist object including its generated ID.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/watchlists \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: sk_live_abc123def456\" \\\n -d '{\"name\": \"Halal Tech\", \"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"]}'\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.halalterminal.com/api/watchlists\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n json={\"name\": \"Halal Tech\", \"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"]},\n)\nwatchlist = resp.json()\n```","operationId":"create_watchlist_api_watchlists_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistCreateRequest"}}},"required":true},"responses":{"200":{"description":"The newly created watchlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistResponse"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/watchlists/{watchlist_id}":{"get":{"tags":["watchlists"],"summary":"Get Watchlist","description":"Get a single watchlist by ID.\n\nReturns the full watchlist object including all symbols. Raises 404\nif the watchlist does not exist.\n\n**curl example**:\n```bash\ncurl https://api.halalterminal.com/api/watchlists/wl_abc123 \\\n -H \"X-API-Key: sk_live_abc123def456\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.halalterminal.com/api/watchlists/wl_abc123\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n)\nwatchlist = resp.json()\n```","operationId":"get_watchlist_api_watchlists__watchlist_id__get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"responses":{"200":{"description":"The requested watchlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistResponse"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Watchlist not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["watchlists"],"summary":"Delete Watchlist","description":"Delete a watchlist.\n\nPermanently removes the watchlist and all its symbol associations.\nReturns a confirmation object. Raises 404 if the watchlist does not\nexist.\n\n**curl example**:\n```bash\ncurl -X DELETE https://api.halalterminal.com/api/watchlists/wl_abc123 \\\n -H \"X-API-Key: sk_live_abc123def456\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.delete(\n \"https://api.halalterminal.com/api/watchlists/wl_abc123\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n)\nassert resp.json()[\"deleted\"] is True\n```","operationId":"delete_watchlist_api_watchlists__watchlist_id__delete","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"responses":{"200":{"description":"Confirmation that the watchlist was deleted","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Watchlist not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/watchlists/{watchlist_id}/symbols":{"post":{"tags":["watchlists"],"summary":"Add Symbol To Watchlist","description":"Add a symbol to an existing watchlist.\n\nAppends a single ticker symbol to the watchlist. Returns the updated\nwatchlist. Raises 404 if the watchlist does not exist.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/watchlists/wl_abc123/symbols \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: sk_live_abc123def456\" \\\n -d '{\"symbol\": \"AMZN\"}'\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.halalterminal.com/api/watchlists/wl_abc123/symbols\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n json={\"symbol\": \"AMZN\"},\n)\nupdated = resp.json()\n```","operationId":"add_symbol_to_watchlist_api_watchlists__watchlist_id__symbols_post","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistSymbolRequest"}}}},"responses":{"200":{"description":"The updated watchlist with the new symbol added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistResponse"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Watchlist not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/watchlists/{watchlist_id}/symbols/{symbol}":{"delete":{"tags":["watchlists"],"summary":"Remove Symbol From Watchlist","description":"Remove a symbol from a watchlist.\n\nRemoves the specified ticker symbol from the watchlist. Returns the\nupdated watchlist. Raises 404 if the watchlist does not exist.\n\n**curl example**:\n```bash\ncurl -X DELETE https://api.halalterminal.com/api/watchlists/wl_abc123/symbols/AMZN \\\n -H \"X-API-Key: sk_live_abc123def456\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.delete(\n \"https://api.halalterminal.com/api/watchlists/wl_abc123/symbols/AMZN\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n)\nupdated = resp.json()\n```","operationId":"remove_symbol_from_watchlist_api_watchlists__watchlist_id__symbols__symbol__delete","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"The updated watchlist with the symbol removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistResponse"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Watchlist not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/compare":{"post":{"tags":["comparison"],"summary":"Compare Symbols","description":"Compare Shariah compliance across multiple symbols.\n\nAccepts 2-5 ticker symbols and returns screening results, market\nquotes, and stored database data for each symbol side by side.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/compare \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: sk_live_abc123def456\" \\\n -d '{\"symbols\": [\"AAPL\", \"MSFT\"]}'\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.halalterminal.com/api/compare\",\n headers={\"X-API-Key\": \"sk_live_abc123def456\"},\n json={\"symbols\": [\"AAPL\", \"MSFT\"]},\n)\ncomparison = resp.json()\nfor item in comparison[\"items\"]:\n print(item[\"symbol\"], item[\"screening\"][\"status\"])\n```","operationId":"compare_symbols_api_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":true},"responses":{"200":{"description":"Side-by-side compliance comparison for the requested symbols","content":{"application/json":{"schema":{"$ref":"#/components/schemas/backend__schemas__comparison__CompareResponse"}}}},"400":{"description":"Fewer than 2 or more than 5 symbols provided"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/education/glossary":{"get":{"tags":["education"],"summary":"Get Glossary","description":"Retrieve the Islamic finance glossary, optionally filtered by search query.\n\nReturns a list of key Islamic finance terms (e.g. Riba, Gharar, Murabaha,\nSukuk) with their Arabic script, definitions, categories, and scholarly\nreferences. Use the optional query parameter to search for specific terms.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/education/glossary?q=riba\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"http://localhost:8000/api/education/glossary\",\n params={\"q\": \"riba\"},\n)\nfor term in resp.json()[\"terms\"]:\n print(f\"{term['term']} ({term['arabic']}): {term['definition']}\")\n```","operationId":"get_glossary_api_education_glossary_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"List of Islamic finance glossary terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlossaryResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"Methodology 'unknown' not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/education/methodologies":{"get":{"tags":["education"],"summary":"Get Methodologies","description":"List all supported Shariah screening methodologies.\n\nReturns summary information for every screening methodology available in\nthe system, such as AAOIFI, SEC Malaysia, DJIM, MSCI, and FTSE. Each\nentry includes identification, thresholds, and distinguishing features.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/education/methodologies\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/education/methodologies\")\nfor m in resp.json()[\"methodologies\"]:\n print(f\"{m['name']}: {m.get('full_name', 'N/A')}\")\n```","operationId":"get_methodologies_api_education_methodologies_get","responses":{"200":{"description":"List of all available Shariah screening methodologies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodologiesResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"Methodology 'unknown' not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}}}}},"/api/education/methodologies/{name}":{"get":{"tags":["education"],"summary":"Get Methodology","description":"Retrieve detailed information about a specific Shariah screening methodology.\n\nReturns comprehensive details for the requested methodology, including its\nscreening process, financial ratio thresholds, Shariah board information,\nand scholarly references. Use the methodology name or ID as returned by\nthe ``/methodologies`` endpoint (e.g. ``aaoifi``, ``sec``, ``djim``).\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/education/methodologies/aaoifi\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/education/methodologies/aaoifi\")\ndata = resp.json()\nprint(f\"{data['full_name']} (est. {data['established']})\")\nprint(\"Thresholds:\", data[\"thresholds\"])\n```","operationId":"get_methodology_api_education_methodologies__name__get","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}}],"responses":{"200":{"description":"Detailed information for the requested methodology","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodologyDetailResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"Methodology 'unknown' not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/education/screening-criteria":{"get":{"tags":["education"],"summary":"Get Screening Criteria","description":"Retrieve the Shariah compliance screening criteria.\n\nReturns the business activity screening rules (prohibited sectors and\nrevenue thresholds) and financial ratio screening thresholds (debt,\ninterest income, liquid assets) used to determine whether a stock\nis Shariah-compliant.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/education/screening-criteria\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/education/screening-criteria\")\ncriteria = resp.json()\nprint(\"Prohibited sectors:\", criteria[\"business_screening\"].get(\"prohibited_sectors\"))\nprint(\"Max debt ratio:\", criteria[\"financial_screening\"].get(\"max_debt_to_total_assets\"))\n```","operationId":"get_screening_criteria_api_education_screening_criteria_get","responses":{"200":{"description":"Business and financial screening criteria for Shariah compliance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningCriteriaResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"Methodology 'unknown' not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}}}}},"/api/education/purification":{"get":{"tags":["education"],"summary":"Get Purification Guide","description":"Retrieve the dividend purification and zakat guide.\n\nReturns educational content on how to purify investment returns that may\ncontain a haram (impermissible) component. Includes the purification\nformula, guidance on capital gains purification, zakat calculation for\ninvestments, and scholarly references.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/education/purification\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/education/purification\")\nguide = resp.json()\nprint(\"Formula:\", guide[\"purification_formula\"].get(\"formula\"))\nprint(\"Zakat rate:\", guide[\"zakat_on_investments\"].get(\"rate\"))\n```","operationId":"get_purification_guide_api_education_purification_get","responses":{"200":{"description":"Guide for purifying investment income","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurificationGuideResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"Methodology 'unknown' not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}}}}},"/api/news":{"get":{"tags":["news"],"summary":"Get News","description":"Retrieve a paginated list of Islamic finance and market news articles.\n\nReturns news articles from all configured sources, optionally filtered by\nsource, category, or free-text search query. Results are sorted by\npublication date (most recent first) and include sentiment scores.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/news?category=islamic_finance&page=1&page_size=10\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"http://localhost:8000/api/news\",\n params={\"category\": \"islamic_finance\", \"page\": 1, \"page_size\": 10},\n)\ndata = resp.json()\nfor article in data[\"articles\"]:\n print(article[\"title\"], article[\"sentiment\"])\n```","operationId":"get_news_api_news_get","parameters":[{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Paginated list of news articles matching the filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No news articles found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/news/sources":{"get":{"tags":["news"],"summary":"Get Sources","description":"List all configured news sources.\n\nReturns every news feed source available in the system, including its\ncategory, URL, and whether it is currently enabled.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/news/sources\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/news/sources\")\nfor src in resp.json()[\"sources\"]:\n print(src[\"name\"], src[\"category\"], src[\"enabled\"])\n```","operationId":"get_sources_api_news_sources_get","responses":{"200":{"description":"List of all configured news feed sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSourcesResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No news articles found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}}}}},"/api/news/{symbol}":{"get":{"tags":["news"],"summary":"Get News For Symbol","description":"Retrieve recent news articles for a specific stock symbol.\n\nReturns news articles mentioning the given ticker symbol, ranked by\nrelevance and recency. Useful for researching a company before performing\nShariah compliance screening.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/news/AAPL?limit=10\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"http://localhost:8000/api/news/AAPL\",\n params={\"limit\": 10},\n)\ndata = resp.json()\nprint(f\"Found {data['count']} articles for AAPL\")\n```","operationId":"get_news_for_symbol_api_news__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"News articles related to the given ticker symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No news articles found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/filings/{symbol}":{"get":{"tags":["filings"],"summary":"Get Filings","description":"Retrieve SEC EDGAR filings for a company by ticker symbol.\n\nReturns a list of filings (10-K, 10-Q, 8-K, etc.) sourced from the SEC\nEDGAR database. Results can be filtered by filing type and are returned\nin reverse chronological order.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/filings/AAPL?filing_type=10-K&limit=5\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\n \"http://localhost:8000/api/filings/AAPL\",\n params={\"filing_type\": \"10-K\", \"limit\": 5},\n)\ndata = resp.json()\nprint(f\"{data['company_name']} (CIK {data['cik']}): {data['count']} filings\")\nfor f in data[\"filings\"]:\n print(f\" {f['filing_type']} {f['filing_date']} {f['filing_url']}\")\n```","operationId":"get_filings_api_filings__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"filing_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"List of SEC filings for the requested company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingsListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Company or filing not found","content":{"application/json":{"example":{"detail":"No filings found for symbol 'XYZ'"}}}},"429":{"description":"Rate limit exceeded â€” SEC EDGAR enforces strict rate limits","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/filings/{symbol}/facts":{"get":{"tags":["filings"],"summary":"Get Facts","description":"Retrieve XBRL company facts for a ticker symbol.\n\nReturns structured financial data extracted from the company's SEC filings\nvia the EDGAR XBRL API. Facts are organized by taxonomy (e.g. us-gaap)\nand concept (e.g. Revenue, Assets). This data is used internally for\nfinancial-ratio-based Shariah compliance screening.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/filings/MSFT/facts\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/filings/MSFT/facts\")\nfacts = resp.json()[\"facts\"]\n# Access US-GAAP revenue data\nrevenue = facts.get(\"us-gaap\", {}).get(\"Revenue\", {})\nprint(revenue)\n```","operationId":"get_facts_api_filings__symbol__facts_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"XBRL company facts from SEC EDGAR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyFactsResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Company or filing not found","content":{"application/json":{"example":{"detail":"No filings found for symbol 'XYZ'"}}}},"429":{"description":"Rate limit exceeded â€” SEC EDGAR enforces strict rate limits","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/dividends/{symbol}":{"get":{"tags":["dividends"],"summary":"Get Dividend History","description":"Retrieve the dividend payment history for a stock.\n\nReturns every recorded dividend payment for the given symbol, including\nthe payment date and per-share amount in USD, ordered chronologically.\n\n**curl example:**\n\n curl -X GET \"http://localhost:8000/api/dividends/MSFT\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/dividends/MSFT\")\ndata = resp.json()\nprint(f\"{data['symbol']}: {data['count']} dividends\")\nfor d in data[\"dividends\"][-4:]:\n print(f\" {d['date']}: ${d['amount']:.4f}\")\n```","operationId":"get_dividend_history_api_dividends__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Chronological list of historical dividend payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DividendHistoryResponse"}}}},"404":{"description":"Symbol not found or has no dividend history."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/dividends/{symbol}/purification":{"get":{"tags":["dividends"],"summary":"Get Dividend Purification","description":"Calculate dividend purification amounts for a stock.\n\nApplies the company's Shariah purification rate to each historical\ndividend payment and returns per-dividend purification amounts, the\nhalal portion, and aggregate totals.\n\nKey fields in the response:\n- `purification_rate`: the company-level rate (e.g. 0.031 = 3.1%)\n- `total_dividends`: sum of all dividends\n- `total_purification`: total amount to donate\n- `total_halal`: total amount that is halal to keep\n\n**curl example:**\n\n curl -X GET \"http://localhost:8000/api/dividends/MSFT/purification\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/dividends/MSFT/purification\")\ndata = resp.json()\nprint(f\"Purification rate: {data['purification_rate']:.1%}\")\nprint(f\"Total to purify: ${data['total_purification']:.2f}\")\n```","operationId":"get_dividend_purification_api_dividends__symbol__purification_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Dividend purification breakdown with per-payment and total amounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DividendPurificationResponse"}}}},"404":{"description":"Symbol not found or has no dividend/screening data."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/zakat/calculate":{"post":{"tags":["zakat"],"summary":"Calculate Zakat","description":"Calculate zakat owed on a portfolio of stock holdings.\n\nDetermines whether the total market value of the provided holdings exceeds\nthe nisab threshold (85 grams of gold at the given price per gram). If\nabove nisab, calculates 2.5% zakat on each holding. Returns per-holding\nzakat amounts and aggregate totals.\n\nKey response fields:\n- `nisab_threshold`: 85 * gold_price_per_gram\n- `is_above_nisab`: whether zakat is due\n- `total_zakat`: total amount to pay (0 if below nisab)\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/zakat/calculate\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"holdings\": [{\"symbol\": \"AAPL\", \"market_value\": 25000}, {\"symbol\": \"MSFT\", \"market_value\": 18000}], \"gold_price_per_gram\": 65.0}'\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/zakat/calculate\",\n json={\n \"holdings\": [\n {\"symbol\": \"AAPL\", \"market_value\": 25000},\n {\"symbol\": \"MSFT\", \"market_value\": 18000},\n ],\n \"gold_price_per_gram\": 65.0,\n },\n)\ndata = resp.json()\nif data[\"is_above_nisab\"]:\n print(f\"Zakat due: ${data['total_zakat']:.2f}\")\nelse:\n print(\"Below nisab â€” no zakat due\")\n```","operationId":"calculate_zakat_api_zakat_calculate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZakatCalculateRequest"}}},"required":true},"responses":{"200":{"description":"Zakat calculation with nisab check and per-holding breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZakatCalculateResponse"}}}},"401":{"description":"Authentication required (if auth is enabled)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/purification/calculate":{"post":{"tags":["zakat"],"summary":"Calculate Purification","description":"Calculate dividend purification amounts for multiple holdings at once.\n\nFor each holding, looks up its Shariah purification rate and applies it to\nthe provided dividend income to determine how much should be donated. Also\nreturns the halal amount and whether each holding is compliant.\n\nKey response fields:\n- `total_purification`: total dollar amount to donate across all holdings\n- `total_halal`: total halal dividend amount to keep\n- Each holding includes `purification_rate`, `purification_amount`, and\n `is_compliant`\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/purification/calculate\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"holdings\": [{\"symbol\": \"MSFT\", \"dividend_income\": 320}, {\"symbol\": \"AAPL\", \"dividend_income\": 150}]}'\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/purification/calculate\",\n json={\n \"holdings\": [\n {\"symbol\": \"MSFT\", \"dividend_income\": 320},\n {\"symbol\": \"AAPL\", \"dividend_income\": 150},\n ],\n },\n)\ndata = resp.json()\nprint(f\"Total to purify: ${data['total_purification']:.2f}\")\nprint(f\"Halal to keep: ${data['total_halal']:.2f}\")\n```","operationId":"calculate_purification_api_purification_calculate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurificationCalculateRequest"}}},"required":true},"responses":{"200":{"description":"Purification amounts per holding with halal/non-halal split.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurificationCalculateResponse"}}}},"401":{"description":"Authentication required (if auth is enabled)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/screening/{symbol}":{"get":{"tags":["reports"],"summary":"Get Screening Report","description":"Generate a Shariah compliance screening report for a single stock.\n\nReturns a comprehensive report including business activity screening,\nfinancial ratio analysis, and an overall compliance determination for\nthe given ticker symbol. The report uses the configured screening\nmethodology (e.g. AAOIFI thresholds).\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/reports/screening/AAPL\"\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/reports/screening/AAPL\")\nreport = resp.json()\nprint(f\"Symbol: {report['symbol']}\")\nprint(f\"Compliant: {report['screening']['is_compliant']}\")\nprint(f\"Generated: {report['report_generated_at']}\")\n```","operationId":"get_screening_report_api_reports_screening__symbol__get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Full Shariah compliance screening report for the symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningReportResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No screening data found for symbol 'XYZ'"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/portfolio":{"post":{"tags":["reports"],"summary":"Get Portfolio Report","description":"Generate a Shariah compliance report for a portfolio of stocks.\n\nAccepts a list of ticker symbols and returns an aggregated report with\nper-holding compliance results, overall compliance percentage, and\nsummary counts. Useful for screening an entire portfolio at once.\n\n**curl example:**\n```bash\ncurl -X POST \"http://localhost:8000/api/reports/portfolio\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"symbols\": [\"AAPL\", \"MSFT\", \"AMZN\"]}'\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.post(\n \"http://localhost:8000/api/reports/portfolio\",\n json={\"symbols\": [\"AAPL\", \"MSFT\", \"AMZN\"]},\n)\nreport = resp.json()\nprint(f\"Compliance: {report['compliance_percentage']}%\")\nprint(f\"Compliant: {report['compliant']}/{report['total']}\")\n```","operationId":"get_portfolio_report_api_reports_portfolio_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioReportRequest"}}},"required":true},"responses":{"200":{"description":"Aggregated Shariah compliance report for the portfolio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioReportResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No screening data found for symbol 'XYZ'"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}},"400":{"description":"Invalid request â€” at least one symbol is required","content":{"application/json":{"example":{"detail":"At least 1 symbol required"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/export/csv":{"get":{"tags":["reports"],"summary":"Export Csv","description":"Export all cached screening results as a downloadable CSV file.\n\nReturns a CSV file containing the most recent screening results for all\npreviously screened stocks. The file is served as a streaming download\nwith the filename ``screening_results.csv``.\n\n**curl example:**\n```bash\ncurl -X GET \"http://localhost:8000/api/reports/export/csv\" -o screening_results.csv\n```\n\n**Python requests example:**\n```python\nimport requests\n\nresp = requests.get(\"http://localhost:8000/api/reports/export/csv\")\nwith open(\"screening_results.csv\", \"w\") as f:\n f.write(resp.text)\n```","operationId":"export_csv_api_reports_export_csv_get","responses":{"200":{"description":"CSV file with screening results","content":{"application/json":{"schema":{}},"text/csv":{"example":"symbol,is_compliant,methodology,debt_ratio,interest_ratio\nAAPL,True,aaoifi,0.25,0.01\nMSFT,True,aaoifi,0.18,0.02\n"}}},"401":{"description":"Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"No screening data found for symbol 'XYZ'"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"example":{"detail":"Rate limit exceeded. Try again in 60 seconds."}}}}}}},"/api/etf/{symbol}/holdings":{"get":{"tags":["etf"],"summary":"Get Etf Holdings","description":"Retrieve the full list of holdings for an ETF.\n\nReturns every underlying position with its ticker, name, portfolio weight,\nshare count, market value, and Shariah compliance status (if previously\nscreened).\n\n**curl example:**\n\n curl -X GET \"http://localhost:8000/api/etf/VTI/holdings\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/etf/VTI/holdings\")\ndata = resp.json()\nprint(data[\"holdings_count\"], \"holdings\")\n```","operationId":"get_etf_holdings_api_etf__symbol__holdings_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"ETF holdings list with weights and compliance statuses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFHoldingsResponse"}}}},"404":{"description":"ETF symbol not found or has no holdings data."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/{symbol}/info":{"get":{"tags":["etf"],"summary":"Get Etf Info","description":"Retrieve general fund information for an ETF.\n\nReturns metadata such as the fund name, description, inception date,\nexpense ratio, NAV, total assets, category, sector weightings, and\ncountry weightings.\n\n**curl example:**\n\n curl -X GET \"http://localhost:8000/api/etf/SPY/info\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/etf/SPY/info\")\ninfo = resp.json()\nprint(info[\"name\"], \"- expense ratio:\", info[\"expense_ratio\"])\n```","operationId":"get_etf_info_api_etf__symbol__info_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Fund-level metadata including expense ratio, AUM, sector weightings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFFundInfoResponse"}}}},"404":{"description":"ETF symbol not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/{symbol}/screen":{"post":{"tags":["etf"],"summary":"Screen Etf","description":"Run a Shariah compliance screening on an ETF.\n\nScreens every holding in the ETF against Shariah compliance criteria and\nreturns an overall compliance status, a weighted-average purification rate,\na compliance summary (counts and weights), and per-holding screening\nresults. Pass `force_refresh=true` to bypass cached results â€” available\nonly for enterprise and internal plans; for other plans the flag is\nsilently treated as False.\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/etf/VTI/screen?force_refresh=false\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\"http://localhost:8000/api/etf/VTI/screen\", params={\"force_refresh\": False})\nresult = resp.json()\nprint(result[\"compliance_status\"], \"- compliant weight:\", result[\"summary\"][\"compliant_weight\"])\n```","operationId":"screen_etf_api_etf__symbol__screen_post","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"force_refresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force Refresh"}}],"responses":{"200":{"description":"Full Shariah screening result with per-holding compliance details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFScreeningResponse"}}}},"404":{"description":"ETF symbol not found or has no holdings data."},"429":{"description":"Rate limit exceeded. Try again later."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/{symbol}/screening":{"get":{"tags":["etf"],"summary":"Get Etf Screening","description":"Retrieve a previously cached Shariah screening result for an ETF.\n\nUnlike the POST `/screen` endpoint, this does **not** trigger a new\nscreening run. It returns the most recent cached result, or 404 if no\nscreening has been performed yet.\n\n**curl example:**\n\n curl -X GET \"http://localhost:8000/api/etf/VTI/screening\"\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.get(\"http://localhost:8000/api/etf/VTI/screening\")\nif resp.status_code == 200:\n print(resp.json()[\"compliance_status\"])\nelse:\n print(\"No cached screening available\")\n```","operationId":"get_etf_screening_api_etf__symbol__screening_get","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"responses":{"200":{"description":"Cached Shariah screening result, if available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFScreeningResponse"}}}},"404":{"description":"No cached screening found for this ETF symbol."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/{symbol}/purification":{"post":{"tags":["etf"],"summary":"Calculate Etf Purification","description":"Calculate the purification amount for an ETF investment.\n\nGiven an investment amount and optional dividend income, computes how much\nmoney should be donated to purify returns based on each holding's\npurification rate. Returns both aggregate amounts and a per-holding\nbreakdown.\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/etf/VTI/purification\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"investment_amount\": 50000, \"dividend_income\": 1200}'\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/etf/VTI/purification\",\n json={\"investment_amount\": 50000, \"dividend_income\": 1200},\n)\ndata = resp.json()\nprint(f\"Total to purify: ${data['total_purification_amount']:.2f}\")\n```","operationId":"calculate_etf_purification_api_etf__symbol__purification_post","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFPurificationRequest"}}}},"responses":{"200":{"description":"Purification amounts for the investment and optional dividend income.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFPurificationResponse"}}}},"404":{"description":"ETF symbol not found or has no screening data."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/compare":{"post":{"tags":["etf"],"summary":"Compare Etfs","description":"Compare two to five ETFs side by side.\n\nReturns per-ETF summary data (holdings count, expense ratio, compliance\nstatus, compliant/non-compliant weights) and identifies holdings that\noverlap across multiple ETFs with their respective weights.\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/etf/compare\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"symbols\": [\"VTI\", \"SPY\", \"SCHB\"]}'\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/etf/compare\",\n json={\"symbols\": [\"VTI\", \"SPY\"]},\n)\ndata = resp.json()\nprint(f\"Overlap: {data['overlap_count']} holdings\")\n```","operationId":"compare_etfs_api_etf_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFCompareRequest"}}},"required":true},"responses":{"200":{"description":"Side-by-side ETF comparison with overlap analysis.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFCompareResponse"}}}},"404":{"description":"One or more ETF symbols not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/etf/screen-bulk":{"post":{"tags":["etf"],"summary":"Screen Bulk","description":"Screen multiple ETFs for Shariah compliance in a single request.\n\nAccepts up to 100 ETF symbols and returns each ETF's compliance status,\ncompliant/non-compliant weights, and purification rate. Also includes a\nsummary with total/compliant/non-compliant/error counts. Pass\n`force_refresh=true` to bypass cached results â€” available only for\nenterprise and internal plans; for other plans the flag is silently\ntreated as False.\n\n**curl example:**\n\n curl -X POST \"http://localhost:8000/api/etf/screen-bulk\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"symbols\": [\"VTI\", \"SPY\", \"SCHB\"], \"force_refresh\": false}'\n\n**Python requests example:**\n\n```python\nimport requests\nresp = requests.post(\n \"http://localhost:8000/api/etf/screen-bulk\",\n json={\"symbols\": [\"VTI\", \"SPY\", \"SCHB\"], \"force_refresh\": False},\n)\ndata = resp.json()\nprint(f\"Compliant: {data['summary']['compliant']}/{data['summary']['total']}\")\n```","operationId":"screen_bulk_api_etf_screen_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFBulkScreenRequest"}}},"required":true},"responses":{"200":{"description":"Bulk screening results with per-ETF statuses and aggregate summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETFBulkScreenResponse"}}}},"429":{"description":"Rate limit exceeded. Try again later."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keys/generate":{"post":{"tags":["api-keys"],"summary":"Generate Key","description":"Generate a free-trial API key.\n\nCreates a new API key with 500 free tokens for the given email\naddress. If a key already exists for this email, behavior depends\non backend configuration.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/keys/generate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"dev@example.com\"}'\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.halalterminal.com/api/keys/generate\",\n json={\"email\": \"dev@example.com\"},\n)\nkey_data = resp.json()\nprint(\"Your API key:\", key_data[\"api_key\"])\n```","operationId":"generate_key_api_keys_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateKeyRequest"}}},"required":true},"responses":{"200":{"description":"The newly generated API key with plan details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateKeyResponse"}}}},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/revoke":{"post":{"tags":["api-keys"],"summary":"Revoke Key","description":"Deactivate a key by its public prefix. Internal-plan callers only.\n\nUsed by the admin dashboard to revoke a customer key without ever\nhandling the raw key value (which is bcrypt-hashed at rest and not\nrecoverable after creation).","operationId":"revoke_key_api_keys_revoke_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeKeyRequest"}}},"required":true},"responses":{"200":{"description":"Revoked status","content":{"application/json":{"schema":{}}}},"403":{"description":"Internal-only endpoint"},"404":{"description":"Key not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/token-costs":{"get":{"tags":["api-keys"],"summary":"Get Token Costs","description":"Return the full token cost table.\n\nLists every endpoint pattern and how many tokens each request costs.\nUse this to estimate usage before making API calls. No authentication\nrequired.\n\n**curl example**:\n```bash\ncurl https://api.halalterminal.com/api/keys/token-costs\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\"https://api.halalterminal.com/api/keys/token-costs\")\nfor cost in resp.json()[\"costs\"]:\n print(f\"{cost['pattern']} ({cost['method']}): {cost['tokens']} tokens\")\n```","operationId":"get_token_costs_api_keys_token_costs_get","responses":{"200":{"description":"Token cost table for all endpoint categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCostsResponse"}}}}},"security":[]}},"/api/keys/{api_key}/usage":{"get":{"tags":["api-keys"],"summary":"Get Usage","description":"Retrieve usage statistics for an API key.\n\nRequires authentication via X-API-Key header. You can only view\nusage for your own key.\n\n**curl example**:\n```bash\ncurl -H \"X-API-Key: ht_abc123def456\" https://api.halalterminal.com/api/keys/ht_abc123def456/usage\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.halalterminal.com/api/keys/ht_abc123def456/usage\",\n headers={\"X-API-Key\": \"ht_abc123def456\"},\n)\nusage = resp.json()\nprint(f\"Used {usage['tokens_used']}/{usage['tokens_limit']} tokens\")\n```","operationId":"get_usage_api_keys__api_key__usage_get","parameters":[{"name":"api_key","in":"path","required":true,"schema":{"type":"string","title":"Api Key"}}],"responses":{"200":{"description":"Usage statistics for the API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyUsageResponse"}}}},"403":{"description":"Caller does not own this API key"},"404":{"description":"API key not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/{api_key}/usage/daily":{"get":{"tags":["api-keys"],"summary":"Get Daily Usage","description":"Return per-day request and token counts for the last N days.\n\nRequires authentication via X-API-Key header. You can only view\nusage for your own key. The ``days`` query parameter controls how\nfar back to look (default 30).\n\n**curl example**:\n```bash\ncurl -H \"X-API-Key: ht_abc123def456\" \"https://api.halalterminal.com/api/keys/ht_abc123def456/usage/daily?days=7\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.halalterminal.com/api/keys/ht_abc123def456/usage/daily\",\n headers={\"X-API-Key\": \"ht_abc123def456\"},\n params={\"days\": 7},\n)\nfor day in resp.json()[\"daily\"]:\n print(day[\"date\"], day[\"count\"], \"requests,\", day[\"tokens\"], \"tokens\")\n```","operationId":"get_daily_usage_api_keys__api_key__usage_daily_get","parameters":[{"name":"api_key","in":"path","required":true,"schema":{"type":"string","title":"Api Key"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Days"}}],"responses":{"200":{"description":"Per-day request and token counts for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyUsageResponse"}}}},"403":{"description":"Caller does not own this API key"},"404":{"description":"API key not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/{api_key}/usage/recent":{"get":{"tags":["api-keys"],"summary":"Get Recent Requests","description":"Return the most recent individual API requests.\n\nRequires authentication via X-API-Key header. You can only view\nusage for your own key. The ``limit`` query parameter controls how\nmany entries to return (default 20).\n\n**curl example**:\n```bash\ncurl -H \"X-API-Key: ht_abc123def456\" \"https://api.halalterminal.com/api/keys/ht_abc123def456/usage/recent?limit=10\"\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\n \"https://api.halalterminal.com/api/keys/ht_abc123def456/usage/recent\",\n headers={\"X-API-Key\": \"ht_abc123def456\"},\n params={\"limit\": 10},\n)\nfor req in resp.json()[\"requests\"]:\n print(req[\"timestamp\"], req[\"method\"], req[\"endpoint\"], req[\"tokens_charged\"], \"tokens\")\n```","operationId":"get_recent_requests_api_keys__api_key__usage_recent_get","parameters":[{"name":"api_key","in":"path","required":true,"schema":{"type":"string","title":"Api Key"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Most recent individual API requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentRequestsResponse"}}}},"403":{"description":"Caller does not own this API key"},"404":{"description":"API key not found"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/{api_key}/regenerate":{"post":{"tags":["api-keys"],"summary":"Regenerate Key","description":"Deactivate an API key and issue a replacement.\n\n**Requires authentication via X-API-Key header. The caller must be the\nowner of the key being regenerated** â€” you can only regenerate your own\nkey. After regeneration the old key is permanently deactivated; use the\nreturned `new_key` for all subsequent requests.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/keys/ht_abc123/regenerate \\\n -H \"X-API-Key: ht_abc123\"\n```","operationId":"regenerate_key_api_keys__api_key__regenerate_post","parameters":[{"name":"api_key","in":"path","required":true,"schema":{"type":"string","title":"Api Key"}}],"responses":{"200":{"description":"The old (deactivated) key and the new replacement key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegenerateKeyResponse"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Caller does not own this key"},"404":{"description":"API key not found or already inactive"},"429":{"description":"Rate limit exceeded"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/keys/plans":{"get":{"tags":["api-keys"],"summary":"List Plans","description":"List all available API plans with pricing.\n\nReturns every plan tier including name, monthly price, token\nlimits, overage rates, and included features. No authentication required.\n\n**curl example**:\n```bash\ncurl https://api.halalterminal.com/api/keys/plans\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.get(\"https://api.halalterminal.com/api/keys/plans\")\nfor plan in resp.json()[\"plans\"]:\n print(f\"{plan['display_name']}: ${plan['price_monthly']}/mo â€” {plan['tokens_limit']} tokens\")\n```","operationId":"list_plans_api_keys_plans_get","responses":{"200":{"description":"All available API subscription plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlansResponse"}}}},"429":{"description":"Rate limit exceeded"}},"security":[]}},"/api/auth/me":{"get":{"tags":["auth"],"summary":"Me","description":"Return plan, quota, and identity for the calling API key.\n\nRequires the X-API-Key header. Calling this endpoint does not consume\ntokens â€” it's safe to poll for live quota state.\n\n**curl example**:\n```bash\ncurl -H \"X-API-Key: ht_abc123\" https://api.halalterminal.com/api/auth/me\n```","operationId":"me_api_auth_me_get","responses":{"200":{"description":"Plan, quota, and identity for the calling API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyUsageResponse"}}}},"401":{"description":"Missing or invalid API key"}}}},"/api/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Checkout","description":"Create a Stripe Checkout session for a plan upgrade.\n\nGenerates a hosted Stripe Checkout page for upgrading from the\ncurrent plan to the specified target plan (starter, pro, or\nenterprise). The returned URL should be opened in the user's\nbrowser to complete payment.\n\n**curl example**:\n```bash\ncurl -X POST https://api.halalterminal.com/api/billing/checkout \\\n -H \"Content-Type: application/json\" \\\n -d '{\"api_key\": \"ht_abc123def456\", \"plan\": \"starter\"}'\n```\n\n**Python example**:\n```python\nimport requests\n\nresp = requests.post(\n \"https://api.halalterminal.com/api/billing/checkout\",\n json={\"api_key\": \"ht_abc123def456\", \"plan\": \"starter\"},\n)\ncheckout = resp.json()\nprint(\"Pay here:\", checkout[\"checkout_url\"])\n```","operationId":"create_checkout_api_billing_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Stripe checkout session URL and ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"400":{"description":"No Stripe price configured for the requested plan"},"404":{"description":"API key not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Stripe is not configured or SDK not installed"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/billing/webhook":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Handle Stripe webhook events for subscription lifecycle.\n\nProcesses ``checkout.session.completed`` (plan upgrade),\n``customer.subscription.deleted`` (downgrade to free, sub-canceled email),\n``invoice.paid`` (receipt email + overage settlement), and\n``invoice.payment_failed`` (action-required email) events sent by Stripe.\nThis endpoint verifies the webhook signature before processing.\n\n**curl example**:\n```bash\n# Typically called by Stripe, but for local testing with the Stripe CLI:\nstripe listen --forward-to localhost:8000/api/billing/webhook\n```\n\n**Python example**:\n```python\n# Webhook endpoints are called by Stripe, not by your application.\n# Use the Stripe CLI or Dashboard to inspect delivered events.\n```","operationId":"stripe_webhook_api_billing_webhook_post","responses":{"200":{"description":"Acknowledgement that the webhook event was received","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid webhook signature"},"503":{"description":"Webhook secret not configured"}},"security":[]}},"/api/billing/portal":{"post":{"tags":["billing"],"summary":"Create Portal Session","description":"Create a Stripe Customer Portal session for the given API key.\n\nThe portal lets the user update their payment method, view invoices,\nand cancel their subscription. Requires the key to have an associated\nStripe customer (i.e. has paid at least once).","operationId":"create_portal_session_api_billing_portal_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRequest"}}},"required":true},"responses":{"200":{"description":"Stripe Customer Portal session URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}},"400":{"description":"Key has no active paid subscription"},"404":{"description":"API key not found"},"503":{"description":"Stripe not configured or Customer Portal not enabled"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/unsubscribe/{token}":{"get":{"tags":["unsubscribe"],"summary":"Unsubscribe Get","operationId":"unsubscribe_get_api_unsubscribe__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["unsubscribe"],"summary":"Unsubscribe Post","description":"RFC 8058 one-click unsubscribe (called automatically by Gmail/Outlook).","operationId":"unsubscribe_post_api_unsubscribe__token__post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AssetFullResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"quote":{"anyOf":[{"$ref":"#/components/schemas/QuoteResponse"},{"type":"null"}],"description":"Live quote data from the market data provider"},"screening":{"anyOf":[{"$ref":"#/components/schemas/ScreeningResultResponse"},{"type":"null"}],"description":"Shariah screening result, if available"},"database":{"anyOf":[{"$ref":"#/components/schemas/DatabaseStockResponse"},{"type":"null"}],"description":"Static reference data from the local database"}},"type":"object","required":["symbol"],"title":"AssetFullResponse","example":{"database":{"country":"United States","exchange":"NMS","name":"Apple Inc.","sector":"Technology","symbol":"AAPL","type":"equities"},"quote":{"beta":1.28,"change":1.32,"changePercent":0.71,"dividendYield":0.0055,"high":188.5,"low":185.73,"marketCap":2890000000000,"name":"Apple Inc.","open":186.12,"peRatio":29.5,"previousClose":186.12,"price":187.44,"symbol":"AAPL","volume":54638921},"symbol":"AAPL"}},"BatchQuoteRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols","description":"List of ticker symbols to fetch quotes for"}},"type":"object","required":["symbols"],"title":"BatchQuoteRequest"},"BulkScreenRequest":{"properties":{"index_name":{"type":"string","title":"Index Name","description":"Name of the stock index to screen, e.g. 'SP500', 'DJIA'"},"limit":{"anyOf":[{"type":"integer","maximum":500.0},{"type":"null"}],"title":"Limit","description":"Maximum number of tickers to screen (None = all)"},"force_refresh":{"type":"boolean","title":"Force Refresh","description":"Re-screen symbols even if cached results exist","default":false}},"type":"object","required":["index_name"],"title":"BulkScreenRequest","example":{"force_refresh":false,"index_name":"SP500","limit":50}},"BulkScreenResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"index_name":{"type":"string","title":"Index Name","description":"Name of the index being screened, e.g. 'SP500'"},"total":{"type":"integer","title":"Total","description":"Total number of tickers queued for screening"},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"List of ticker symbols included in this run"},"status":{"type":"string","title":"Status","default":"triggered"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"queue_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Queue Job Id"}},"type":"object","required":["run_id","index_name","total","tickers"],"title":"BulkScreenResponse","example":{"count":503,"created_at":"2025-01-15T08:00:00Z","index_name":"SP500","message":"Bulk screening triggered for SP500","run_id":"run_2025-01-15_sp500","status":"triggered","tickers":["AAPL","MSFT","GOOGL","AMZN","..."],"total":503}},"BulkStatusResponse":{"properties":{"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"running":{"type":"boolean","title":"Running"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Run lifecycle status: pending, running, completed, cancelled, failed"},"index_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Name"},"total":{"type":"integer","title":"Total","default":0},"done":{"type":"integer","title":"Done","default":0},"failed_count":{"type":"integer","title":"Failed Count","description":"Number of symbols that failed during screening","default":0},"current_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Symbol","description":"Ticker currently being processed"},"progress_pct":{"type":"number","title":"Progress Pct","description":"Completion percentage (0.0 to 100.0)","default":0.0},"estimated_remaining_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Remaining Seconds"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Most recent error message, if any"}},"additionalProperties":true,"type":"object","required":["running"],"title":"BulkStatusResponse","example":{"created_at":"2025-01-15T08:00:00Z","current_symbol":"MSFT","done":247,"estimated_remaining_seconds":312,"failed_count":3,"index_name":"SP500","progress_pct":49.1,"run_id":"run_2025-01-15_sp500","running":true,"started_at":"2025-01-15T08:00:01Z","status":"running","total":503,"updated_at":"2025-01-15T08:05:23Z"}},"CancelResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"status":{"type":"string","title":"Status"},"done":{"type":"integer","title":"Done","description":"Number of symbols that were screened before cancellation"},"total":{"type":"integer","title":"Total","description":"Total number of symbols that were queued"}},"type":"object","required":["run_id","status","done","total"],"title":"CancelResponse","example":{"done":247,"run_id":"run_2025-01-15_sp500","status":"cancelled","total":503}},"CheckoutRequest":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"API key to upgrade"},"plan":{"type":"string","title":"Plan","description":"Target plan name (starter, pro, or enterprise)"}},"type":"object","required":["api_key","plan"],"title":"CheckoutRequest","description":"Request body for creating a Stripe checkout session.","example":{"api_key":"ht_abc123def456","plan":"starter"}},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url","description":"Stripe-hosted checkout page URL"},"session_id":{"type":"string","title":"Session Id","description":"Stripe checkout session identifier"}},"type":"object","required":["checkout_url","session_id"],"title":"CheckoutResponse","description":"Response containing the Stripe checkout session URL.","example":{"checkout_url":"https://checkout.stripe.com/c/pay/cs_test_abc123","session_id":"cs_test_abc123"}},"CompanyFactsResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the company"},"cik":{"type":"string","title":"Cik","description":"SEC Central Index Key (CIK) number for the company"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Official company name as registered with the SEC"},"facts":{"additionalProperties":true,"type":"object","title":"Facts","description":"XBRL facts organized by taxonomy (e.g. 'us-gaap', 'dei') and concept"}},"type":"object","required":["symbol","cik","facts"],"title":"CompanyFactsResponse","description":"XBRL company facts from SEC EDGAR.","example":{"cik":"0000320193","company_name":"Apple Inc.","facts":{"us-gaap":{"Revenue":{"label":"Revenue","units":{"USD":[{"fy":2023,"val":383285000000}]}}}},"symbol":"AAPL"}},"CompareChange":{"properties":{"symbol":{"type":"string","title":"Symbol"},"change":{"type":"string","title":"Change","description":"Type of change: became_compliant, became_non_compliant, added, or removed"},"run_a_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Run A Compliant"},"run_b_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Run B Compliant"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Human-readable explanation for the compliance change"}},"type":"object","required":["symbol","change"],"title":"CompareChange"},"CompareItemResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol for this comparison item"},"screening":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Screening","description":"Shariah screening result including compliance status"},"quote":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quote","description":"Latest market quote data"},"database":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Database","description":"Stored company data from the database"}},"additionalProperties":true,"type":"object","required":["symbol"],"title":"CompareItemResponse","description":"Compliance and quote data for a single symbol in a comparison.","example":{"database":{"sector":"Technology"},"quote":{"currency":"USD","price":198.5},"screening":{"revenue_breakdown":{"doubtful":5.0,"halal":95.0},"status":"COMPLIANT"},"symbol":"AAPL"}},"CompareRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols","description":"List of 2-5 stock ticker symbols to compare"}},"type":"object","required":["symbols"],"title":"CompareRequest","description":"Request body for comparing Shariah compliance across multiple symbols.","example":{"symbols":["AAPL","MSFT"]}},"CompareSummary":{"properties":{"newly_compliant":{"type":"integer","title":"Newly Compliant","description":"Symbols that became compliant in run B"},"newly_non_compliant":{"type":"integer","title":"Newly Non Compliant","description":"Symbols that became non-compliant in run B"},"unchanged_compliant":{"type":"integer","title":"Unchanged Compliant"},"unchanged_non_compliant":{"type":"integer","title":"Unchanged Non Compliant"},"added_symbols":{"type":"integer","title":"Added Symbols","description":"Symbols present in run B but not in run A"},"removed_symbols":{"type":"integer","title":"Removed Symbols","description":"Symbols present in run A but not in run B"}},"type":"object","required":["newly_compliant","newly_non_compliant","unchanged_compliant","unchanged_non_compliant","added_symbols","removed_symbols"],"title":"CompareSummary"},"CountStatsResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Total count of items in this category","default":0}},"type":"object","title":"CountStatsResponse"},"DailyUsageEntry":{"properties":{"date":{"type":"string","title":"Date","description":"Calendar date in YYYY-MM-DD format"},"count":{"type":"integer","title":"Count","description":"Number of API requests made on this date"},"tokens":{"type":"integer","title":"Tokens","description":"Total tokens charged on this date","default":0}},"type":"object","required":["date","count"],"title":"DailyUsageEntry","description":"Request count and token usage for a single day.","example":{"count":12,"date":"2025-06-15","tokens":48}},"DailyUsageResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The API key these stats belong to"},"days":{"type":"integer","title":"Days","description":"Number of days included in the breakdown"},"daily":{"items":{"$ref":"#/components/schemas/DailyUsageEntry"},"type":"array","title":"Daily","description":"Per-day request and token counts"}},"type":"object","required":["api_key","days","daily"],"title":"DailyUsageResponse","description":"Per-day usage breakdown for an API key.","example":{"api_key":"ht_abc123def456","daily":[{"count":12,"date":"2025-06-15","tokens":48},{"count":8,"date":"2025-06-14","tokens":32}],"days":30}},"DatabaseSearchItemResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company or asset name"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type, e.g. equities, etfs, funds"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Sector classification"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Industry classification"},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Exchange where the asset is listed"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of incorporation or domicile"},"market_cap":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Cap","description":"Market capitalization bucket (e.g. Large, Mid, Small)"}},"additionalProperties":true,"type":"object","required":["symbol"],"title":"DatabaseSearchItemResponse","example":{"country":"United States","exchange":"NMS","industry":"Consumer Electronics","market_cap":"Large","name":"Apple Inc.","sector":"Technology","symbol":"AAPL","type":"equities"}},"DatabaseSearchResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of results matching the query"},"limit":{"type":"integer","title":"Limit","description":"Maximum number of results returned per page"},"offset":{"type":"integer","title":"Offset","description":"Offset into the full result set"},"results":{"items":{"$ref":"#/components/schemas/DatabaseSearchItemResponse"},"type":"array","title":"Results","description":"Page of matching search results"}},"type":"object","required":["total","limit","offset","results"],"title":"DatabaseSearchResponse","example":{"limit":100,"offset":0,"results":[{"country":"United States","exchange":"NMS","industry":"Consumer Electronics","market_cap":"Large","name":"Apple Inc.","sector":"Technology","symbol":"AAPL","type":"equities"}],"total":1}},"DatabaseStatsResponse":{"properties":{"equities":{"$ref":"#/components/schemas/EquitiesStatsResponse","description":"Aggregate statistics for equities"},"etfs":{"$ref":"#/components/schemas/CountStatsResponse","description":"Aggregate statistics for ETFs"},"funds":{"$ref":"#/components/schemas/CountStatsResponse","description":"Aggregate statistics for mutual funds"},"indices":{"$ref":"#/components/schemas/CountStatsResponse","description":"Aggregate statistics for indices"},"screening_results":{"$ref":"#/components/schemas/CountStatsResponse","description":"Count of available Shariah screening results"}},"type":"object","required":["equities","etfs","funds","indices","screening_results"],"title":"DatabaseStatsResponse","example":{"equities":{"count":12450,"countries":78,"sectors":11},"etfs":{"count":3200},"funds":{"count":1540},"indices":{"count":85},"screening_results":{"count":4200}}},"DatabaseStockResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type, e.g. equities, etfs, funds"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company or asset name"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Sector classification"},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Exchange where the asset is listed"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of incorporation or domicile"}},"additionalProperties":true,"type":"object","required":["symbol"],"title":"DatabaseStockResponse","example":{"country":"United States","exchange":"NMS","name":"Apple Inc.","sector":"Technology","symbol":"AAPL","type":"equities"}},"DeleteRunResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"deleted":{"type":"boolean","title":"Deleted","description":"Whether the run was successfully deleted"}},"type":"object","required":["run_id","deleted"],"title":"DeleteRunResponse","example":{"deleted":true,"run_id":"run_2025-01-15_sp500"}},"DividendHistoryResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol (e.g. 'MSFT')."},"count":{"type":"integer","title":"Count","description":"Total number of dividend payments returned."},"dividends":{"items":{"$ref":"#/components/schemas/DividendPayment"},"type":"array","title":"Dividends","description":"Chronological list of dividend payments."}},"type":"object","required":["symbol","count","dividends"],"title":"DividendHistoryResponse","description":"Historical dividend payments for a stock.","example":{"count":4,"dividends":[{"amount":0.75,"date":"2025-03-13"},{"amount":0.75,"date":"2025-06-12"},{"amount":0.75,"date":"2025-09-11"},{"amount":0.83,"date":"2025-12-11"}],"symbol":"MSFT"}},"DividendPayment":{"properties":{"date":{"type":"string","title":"Date","description":"Payment date in YYYY-MM-DD format."},"amount":{"type":"number","title":"Amount","description":"Dividend amount per share in USD."}},"type":"object","required":["date","amount"],"title":"DividendPayment","description":"A single dividend payment event.","example":{"amount":0.75,"date":"2025-12-15"}},"DividendPurificationResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol (e.g. 'MSFT')."},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Company-level purification rate (e.g. 0.031 = 3.1%)."},"count":{"type":"integer","title":"Count","description":"Total number of dividend payments included."},"dividends":{"items":{"$ref":"#/components/schemas/PurifiedDividend"},"type":"array","title":"Dividends","description":"List of dividends with purification amounts."},"total_dividends":{"type":"number","title":"Total Dividends","description":"Sum of all dividend amounts in USD."},"total_purification":{"type":"number","title":"Total Purification","description":"Total amount to purify across all dividends in USD."},"total_halal":{"type":"number","title":"Total Halal","description":"Total halal amount after purification in USD."}},"type":"object","required":["symbol","count","dividends","total_dividends","total_purification","total_halal"],"title":"DividendPurificationResponse","description":"Dividend purification breakdown for a stock over its full history.","example":{"count":4,"dividends":[{"amount":0.75,"date":"2025-03-13","halal_amount":0.727,"purification_amount":0.023,"purification_rate":0.031},{"amount":0.75,"date":"2025-06-12","halal_amount":0.727,"purification_amount":0.023,"purification_rate":0.031}],"purification_rate":0.031,"symbol":"MSFT","total_dividends":3.08,"total_halal":2.985,"total_purification":0.095}},"ETFBulkScreenItemResult":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"is_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Compliant","description":"Whether the ETF is Shariah-compliant."},"compliance_status":{"type":"string","title":"Compliance Status","description":"Overall compliance status.","default":"unscreened"},"compliant_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compliant Weight","description":"Sum of weights of compliant holdings."},"non_compliant_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Non Compliant Weight","description":"Sum of weights of non-compliant holdings."},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Weighted-average purification rate."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if screening failed for this ETF."}},"type":"object","required":["symbol"],"title":"ETFBulkScreenItemResult","description":"Screening result for one ETF in a bulk screening run.","example":{"compliance_status":"non_compliant","compliant_weight":0.78,"is_compliant":false,"non_compliant_weight":0.19,"purification_rate":0.032,"symbol":"VTI"}},"ETFBulkScreenRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Symbols","description":"List of 1-100 ETF ticker symbols to screen."},"force_refresh":{"type":"boolean","title":"Force Refresh","description":"When true, bypass cached screening results and re-screen from scratch.","default":false}},"type":"object","required":["symbols"],"title":"ETFBulkScreenRequest","description":"Request to screen multiple ETFs in one call.","example":{"force_refresh":false,"symbols":["VTI","SPY","SCHB"]}},"ETFBulkScreenResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ETFBulkScreenItemResult"},"type":"array","title":"Results","description":"Per-ETF screening results.","default":[]},"summary":{"$ref":"#/components/schemas/ETFBulkScreenSummary","description":"Aggregate screening statistics.","default":{"total":0,"compliant":0,"non_compliant":0,"errors":0}}},"type":"object","title":"ETFBulkScreenResponse","description":"Response for a bulk ETF screening operation.","example":{"results":[{"compliance_status":"non_compliant","compliant_weight":0.78,"is_compliant":false,"non_compliant_weight":0.19,"purification_rate":0.032,"symbol":"VTI"}],"summary":{"compliant":0,"errors":0,"non_compliant":3,"total":3}}},"ETFBulkScreenSummary":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of ETFs screened.","default":0},"compliant":{"type":"integer","title":"Compliant","description":"Number of compliant ETFs.","default":0},"non_compliant":{"type":"integer","title":"Non Compliant","description":"Number of non-compliant ETFs.","default":0},"errors":{"type":"integer","title":"Errors","description":"Number of ETFs that failed to screen.","default":0}},"type":"object","title":"ETFBulkScreenSummary","description":"Aggregate statistics across all ETFs in a bulk screening run.","example":{"compliant":0,"errors":0,"non_compliant":3,"total":3}},"ETFCompareItem":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"name":{"type":"string","title":"Name","description":"ETF fund name.","default":""},"holdings_count":{"type":"integer","title":"Holdings Count","description":"Number of holdings.","default":0},"total_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Assets","description":"Total assets under management in USD."},"expense_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Expense Ratio","description":"Annual expense ratio as a decimal."},"compliance_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compliance Status","description":"Overall Shariah compliance status."},"compliant_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compliant Weight","description":"Sum of weights of compliant holdings."},"non_compliant_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Non Compliant Weight","description":"Sum of weights of non-compliant holdings."}},"type":"object","required":["symbol"],"title":"ETFCompareItem","description":"Summary comparison data for a single ETF.","example":{"compliance_status":"non_compliant","compliant_weight":0.76,"expense_ratio":0.0945,"holdings_count":503,"name":"SPDR S&P 500 ETF Trust","non_compliant_weight":0.21,"symbol":"SPY","total_assets":500000000000.0}},"ETFCompareRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":2,"title":"Symbols","description":"List of 2-5 ETF ticker symbols to compare."}},"type":"object","required":["symbols"],"title":"ETFCompareRequest","description":"Request body to compare two to five ETFs side by side.","example":{"symbols":["VTI","SPY","SCHB"]}},"ETFCompareResponse":{"properties":{"etfs":{"items":{"$ref":"#/components/schemas/ETFCompareItem"},"type":"array","title":"Etfs","description":"Per-ETF comparison summaries.","default":[]},"overlap_holdings":{"items":{"$ref":"#/components/schemas/ETFOverlapHolding"},"type":"array","title":"Overlap Holdings","description":"Holdings that appear in multiple ETFs.","default":[]},"overlap_count":{"type":"integer","title":"Overlap Count","description":"Total number of overlapping holdings.","default":0}},"type":"object","title":"ETFCompareResponse","description":"Side-by-side comparison of multiple ETFs with overlap analysis.","example":{"etfs":[{"compliance_status":"non_compliant","compliant_weight":0.78,"holdings_count":3500,"name":"Vanguard Total Stock Market ETF","non_compliant_weight":0.19,"symbol":"VTI"},{"compliance_status":"non_compliant","compliant_weight":0.76,"holdings_count":503,"name":"SPDR S&P 500 ETF Trust","non_compliant_weight":0.21,"symbol":"SPY"}],"overlap_count":480,"overlap_holdings":[]}},"ETFComplianceSummary":{"properties":{"total_holdings":{"type":"integer","title":"Total Holdings","description":"Total number of holdings analysed.","default":0},"screened_count":{"type":"integer","title":"Screened Count","description":"Number of holdings that were actually screened.","default":0},"compliant_count":{"type":"integer","title":"Compliant Count","description":"Number of holdings deemed Shariah-compliant.","default":0},"non_compliant_count":{"type":"integer","title":"Non Compliant Count","description":"Number of holdings deemed non-compliant.","default":0},"unscreened_count":{"type":"integer","title":"Unscreened Count","description":"Number of holdings with no screening data.","default":0},"compliant_weight":{"type":"number","title":"Compliant Weight","description":"Sum of weights of compliant holdings (0.0 â€“ 1.0).","default":0.0},"non_compliant_weight":{"type":"number","title":"Non Compliant Weight","description":"Sum of weights of non-compliant holdings (0.0 â€“ 1.0).","default":0.0},"unscreened_weight":{"type":"number","title":"Unscreened Weight","description":"Sum of weights of unscreened holdings (0.0 â€“ 1.0).","default":0.0}},"type":"object","title":"ETFComplianceSummary","description":"Aggregate compliance statistics for an ETF screening run.","example":{"compliant_count":380,"compliant_weight":0.78,"non_compliant_count":105,"non_compliant_weight":0.19,"screened_count":485,"total_holdings":500,"unscreened_count":15,"unscreened_weight":0.03}},"ETFFundInfoResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"name":{"type":"string","title":"Name","description":"ETF fund name.","default":""},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Brief fund description."},"inception_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inception Date","description":"Fund inception date (YYYY-MM-DD)."},"expense_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Expense Ratio","description":"Annual expense ratio as a decimal (0.0003 = 0.03%)."},"nav":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav","description":"Net asset value per share in USD."},"total_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Assets","description":"Total assets under management in USD."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Morningstar or provider category."},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family","description":"Fund family name (e.g. 'Vanguard')."},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Exchange where the ETF is listed (e.g. 'NYSE Arca')."},"sector_weightings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sector Weightings","description":"Mapping of sector names to portfolio weight percentages."},"asset_classes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Asset Classes","description":"Mapping of asset class labels (equity, bond, etc.) to weight percentages."},"country_weightings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Country Weightings","description":"Mapping of country codes/names to portfolio weight percentages."},"turnover":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Turnover","description":"Annual portfolio turnover rate as a decimal."}},"type":"object","required":["symbol"],"title":"ETFFundInfoResponse","description":"General fund-level metadata for an ETF.","example":{"category":"Large Blend","description":"Tracks the S&P 500 index.","exchange":"NYSE Arca","expense_ratio":0.0945,"family":"SPDR State Street Global Advisors","inception_date":"1993-01-22","name":"SPDR S&P 500 ETF Trust","nav":510.25,"sector_weightings":{"healthcare":0.13,"technology":0.3},"symbol":"SPY","total_assets":500000000000.0,"turnover":0.02}},"ETFHoldingPurificationDetail":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the holding."},"name":{"type":"string","title":"Name","description":"Company or security name.","default":""},"weight":{"type":"number","title":"Weight","description":"Portfolio weight as a decimal.","default":0.0},"compliance_status":{"type":"string","title":"Compliance Status","description":"Shariah compliance status.","default":"unscreened"},"purification_rate":{"type":"number","title":"Purification Rate","description":"Purification rate for this holding (e.g. 0.03 = 3%).","default":0.0},"purification_amount":{"type":"number","title":"Purification Amount","description":"Dollar amount to purify for this holding.","default":0.0}},"type":"object","required":["symbol"],"title":"ETFHoldingPurificationDetail","description":"Purification breakdown for a single holding.","example":{"compliance_status":"compliant","name":"Apple Inc.","purification_amount":81.25,"purification_rate":0.025,"symbol":"AAPL","weight":0.065}},"ETFHoldingResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the underlying holding (e.g. 'AAPL')."},"name":{"type":"string","title":"Name","description":"Company or security name.","default":""},"weight":{"type":"number","title":"Weight","description":"Portfolio weight as a decimal (0.05 = 5%).","default":0.0},"shares":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shares","description":"Number of shares held by the ETF."},"market_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Value","description":"Current market value of the position in USD."},"isin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isin","description":"ISIN identifier, if available."},"cusip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cusip","description":"CUSIP identifier, if available."},"compliance_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compliance Status","description":"Shariah compliance status: 'compliant', 'non_compliant', or 'unscreened'."}},"type":"object","required":["symbol"],"title":"ETFHoldingResponse","description":"A single holding within an ETF.","example":{"compliance_status":"compliant","cusip":"037833100","isin":"US0378331005","market_value":32436000.0,"name":"Apple Inc.","shares":180200,"symbol":"AAPL","weight":0.065}},"ETFHoldingScreeningResult":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the holding."},"name":{"type":"string","title":"Name","description":"Company or security name.","default":""},"weight":{"type":"number","title":"Weight","description":"Portfolio weight as a decimal.","default":0.0},"compliance_status":{"type":"string","title":"Compliance Status","description":"Shariah compliance status: 'compliant', 'non_compliant', or 'unscreened'.","default":"unscreened"},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Percentage of income requiring purification (e.g. 0.03 = 3%)."}},"type":"object","required":["symbol"],"title":"ETFHoldingScreeningResult","description":"Screening result for a single holding within an ETF.","example":{"compliance_status":"compliant","name":"Apple Inc.","purification_rate":0.025,"symbol":"AAPL","weight":0.065}},"ETFHoldingsResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"name":{"type":"string","title":"Name","description":"ETF fund name.","default":""},"holdings_count":{"type":"integer","title":"Holdings Count","description":"Total number of holdings in the ETF.","default":0},"holdings":{"items":{"$ref":"#/components/schemas/ETFHoldingResponse"},"type":"array","title":"Holdings","description":"List of individual holdings.","default":[]},"data_source":{"type":"string","title":"Data Source","description":"Provider that supplied the holdings data (e.g. 'yfinance').","default":""}},"type":"object","required":["symbol"],"title":"ETFHoldingsResponse","description":"Complete holdings list for an ETF.","example":{"data_source":"yfinance","holdings":[{"compliance_status":"compliant","market_value":32436000.0,"name":"Apple Inc.","shares":180200,"symbol":"AAPL","weight":0.065},{"compliance_status":"compliant","market_value":28920000.0,"name":"Microsoft Corp.","shares":120500,"symbol":"MSFT","weight":0.058}],"holdings_count":2,"name":"Vanguard Total Stock Market ETF","symbol":"VTI"}},"ETFOverlapHolding":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the overlapping holding."},"name":{"type":"string","title":"Name","description":"Company or security name.","default":""},"etfs":{"items":{"type":"string"},"type":"array","title":"Etfs","description":"ETF symbols containing this holding.","default":[]},"weights":{"additionalProperties":{"type":"number"},"type":"object","title":"Weights","description":"Mapping of ETF symbol to weight for this holding.","default":{}}},"type":"object","required":["symbol"],"title":"ETFOverlapHolding","description":"A holding that appears in more than one of the compared ETFs.","example":{"etfs":["VTI","SPY"],"name":"Apple Inc.","symbol":"AAPL","weights":{"SPY":0.072,"VTI":0.065}}},"ETFPurificationRequest":{"properties":{"investment_amount":{"type":"number","exclusiveMinimum":0.0,"title":"Investment Amount","description":"Total investment amount in USD."},"dividend_income":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Dividend Income","description":"Dividend income received from the ETF in USD."}},"type":"object","required":["investment_amount"],"title":"ETFPurificationRequest","description":"Request body for calculating purification amounts on an ETF investment.","example":{"dividend_income":1200.0,"investment_amount":50000.0}},"ETFPurificationResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"investment_amount":{"type":"number","title":"Investment Amount","description":"Original investment amount in USD.","default":0.0},"dividend_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Income","description":"Dividend income in USD, if provided."},"etf_purification_rate":{"type":"number","title":"Etf Purification Rate","description":"Weighted-average purification rate for the ETF.","default":0.0},"investment_purification_amount":{"type":"number","title":"Investment Purification Amount","description":"Amount to purify from investment gains.","default":0.0},"dividend_purification_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Purification Amount","description":"Amount to purify from dividends."},"total_purification_amount":{"type":"number","title":"Total Purification Amount","description":"Total purification amount (investment + dividends).","default":0.0},"holdings":{"items":{"$ref":"#/components/schemas/ETFHoldingPurificationDetail"},"type":"array","title":"Holdings","description":"Per-holding purification breakdown.","default":[]}},"type":"object","required":["symbol"],"title":"ETFPurificationResponse","description":"Purification calculation result for an ETF investment.","example":{"dividend_income":1200.0,"dividend_purification_amount":38.4,"etf_purification_rate":0.032,"holdings":[],"investment_amount":50000.0,"investment_purification_amount":1600.0,"symbol":"VTI","total_purification_amount":1638.4}},"ETFScreeningResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"ETF ticker symbol."},"name":{"type":"string","title":"Name","description":"ETF fund name.","default":""},"is_compliant":{"type":"boolean","title":"Is Compliant","description":"Whether the ETF is considered Shariah-compliant overall.","default":false},"compliance_status":{"type":"string","title":"Compliance Status","description":"Overall status: 'compliant', 'non_compliant', or 'unscreened'.","default":"unscreened"},"non_compliant_threshold":{"type":"number","title":"Non Compliant Threshold","description":"Maximum non-compliant weight allowed (default 5%).","default":0.05},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Weighted-average purification rate for the ETF."},"summary":{"anyOf":[{"$ref":"#/components/schemas/ETFComplianceSummary"},{"type":"null"}],"description":"Aggregate compliance statistics."},"holdings":{"items":{"$ref":"#/components/schemas/ETFHoldingScreeningResult"},"type":"array","title":"Holdings","description":"Per-holding screening results.","default":[]},"fund_info":{"anyOf":[{"$ref":"#/components/schemas/ETFFundInfoResponse"},{"type":"null"}],"description":"Fund metadata, if available."},"data_source":{"type":"string","title":"Data Source","description":"Data provider used for screening.","default":""}},"type":"object","required":["symbol"],"title":"ETFScreeningResponse","description":"Full Shariah screening result for an ETF, including per-holding details.","example":{"compliance_status":"non_compliant","data_source":"yfinance","holdings":[],"is_compliant":false,"name":"Vanguard Total Stock Market ETF","non_compliant_threshold":0.05,"purification_rate":0.032,"summary":{"compliant_count":380,"compliant_weight":0.78,"non_compliant_count":105,"non_compliant_weight":0.19,"screened_count":485,"total_holdings":500,"unscreened_count":15,"unscreened_weight":0.03},"symbol":"VTI"}},"EndpointStat":{"properties":{"endpoint":{"type":"string","title":"Endpoint","description":"API endpoint path"},"method":{"type":"string","title":"Method","description":"HTTP method (GET, POST, etc.)"},"count":{"type":"integer","title":"Count","description":"Number of requests to this endpoint"},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total tokens charged for this endpoint","default":0}},"type":"object","required":["endpoint","method","count"],"title":"EndpointStat","description":"Hit count for a single API endpoint.","example":{"count":30,"endpoint":"/api/screen","method":"GET","total_tokens":150}},"EquitiesStatsResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Total count of items in this category","default":0},"sectors":{"type":"integer","title":"Sectors","description":"Number of distinct sectors","default":0},"countries":{"type":"integer","title":"Countries","description":"Number of distinct countries","default":0}},"type":"object","title":"EquitiesStatsResponse"},"FilingsListResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the company"},"cik":{"type":"string","title":"Cik","description":"SEC Central Index Key (CIK) number for the company"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Official company name as registered with the SEC"},"count":{"type":"integer","title":"Count","description":"Number of filings returned"},"filings":{"items":{"$ref":"#/components/schemas/SECFilingResponse"},"type":"array","title":"Filings","description":"List of SEC filing records"}},"type":"object","required":["symbol","cik","count","filings"],"title":"FilingsListResponse","description":"Paginated list of SEC filings for a company.","example":{"cik":"0000320193","company_name":"Apple Inc.","count":1,"filings":[{"accession_number":"0000320193-23-000106","filing_date":"2023-11-03","filing_type":"10-K","filing_url":"https://www.sec.gov/Archives/edgar/data/320193/000032019323000106/aapl-20230930.htm","primary_doc_description":"10-K Annual Report","primary_document":"aapl-20230930.htm"}],"symbol":"AAPL"}},"GenerateKeyRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address to associate with the new API key"},"marketing_opt_in":{"type":"boolean","title":"Marketing Opt In","description":"Opt in to occasional product updates and onboarding tips. Defaults to False; transactional emails (key delivery, payment receipts, quota alerts) are always sent regardless.","default":false}},"type":"object","required":["email"],"title":"GenerateKeyRequest","description":"Request body for generating a new free-trial API key.","example":{"email":"dev@example.com","marketing_opt_in":false}},"GenerateKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The generated API key"},"email":{"type":"string","title":"Email","description":"Email address associated with the key"},"plan":{"type":"string","title":"Plan","description":"Plan tier assigned to this key (e.g. free)"},"tokens_limit":{"type":"integer","title":"Tokens Limit","description":"Monthly token allowance"},"tokens_used":{"type":"integer","title":"Tokens Used","description":"Tokens consumed so far this period"},"requests_limit":{"type":"integer","title":"Requests Limit","description":"Maximum number of requests allowed"},"requests_used":{"type":"integer","title":"Requests Used","description":"Number of requests consumed so far"},"billing_period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Period End","description":"ISO-8601 timestamp when the current billing period ends"},"created_at":{"type":"string","title":"Created At","description":"ISO-8601 timestamp when the key was created"}},"type":"object","required":["api_key","email","plan","tokens_limit","tokens_used","requests_limit","requests_used","created_at"],"title":"GenerateKeyResponse","description":"Response returned after successfully generating an API key.","example":{"api_key":"ht_abc123def456","billing_period_end":"2025-07-01T12:00:00Z","created_at":"2025-06-01T12:00:00Z","email":"dev@example.com","plan":"free","requests_limit":50,"requests_used":0,"tokens_limit":500,"tokens_used":0}},"GlossaryResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of glossary terms returned"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"The search query used to filter terms, if any"},"terms":{"items":{"$ref":"#/components/schemas/GlossaryTermResponse"},"type":"array","title":"Terms","description":"List of matching glossary terms"}},"type":"object","required":["count","terms"],"title":"GlossaryResponse","description":"Collection of Islamic finance glossary terms, optionally filtered.","example":{"count":2,"query":"riba","terms":[{"arabic":"Ø±Ø¨Ø§","category":"prohibited_elements","definition":"Interest or usury, prohibited in Islamic finance.","references":["Quran 2:275"],"term":"Riba"},{"arabic":"Ø±Ø¨Ø§ Ø§Ù„ÙØ¶Ù„","category":"prohibited_elements","definition":"Excess in exchange of commodities of the same type.","references":[],"term":"Riba al-Fadl"}]}},"GlossaryTermResponse":{"properties":{"term":{"type":"string","title":"Term","description":"English transliteration of the Islamic finance term"},"arabic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arabic","description":"Original Arabic script for the term"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Topical category, e.g. 'prohibited_elements', 'contracts', 'instruments'"},"definition":{"type":"string","title":"Definition","description":"Detailed explanation of the term in the context of Islamic finance"},"references":{"items":{"type":"string"},"type":"array","title":"References","description":"Scholarly or scriptural references supporting the definition","default":[]}},"type":"object","required":["term","definition"],"title":"GlossaryTermResponse","description":"A single Islamic finance glossary term with its definition.","example":{"arabic":"Ø±Ø¨Ø§","category":"prohibited_elements","definition":"Interest or usury. Any excess compensation without due consideration, prohibited in Islamic finance as it represents unjust enrichment.","references":["Quran 2:275","AAOIFI Shariah Standard No. 3"],"term":"Riba"}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable status message indicating API health"}},"type":"object","required":["message"],"title":"HealthResponse","description":"Response model for the health check endpoint.","example":{"message":"Shariah Screener API is running"}},"IndexInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Index identifier, e.g. 'SP500', 'DJIA', 'NASDAQ100'"},"estimated_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Count","description":"Approximate number of tickers in the index"},"description":{"type":"string","title":"Description","description":"Human-readable description of the index"}},"type":"object","required":["name","description"],"title":"IndexInfo","example":{"description":"S&P 500 â€” large-cap US equities","estimated_count":503,"name":"SP500"}},"IndicesResponse":{"properties":{"indices":{"items":{"$ref":"#/components/schemas/IndexInfo"},"type":"array","title":"Indices","description":"Available stock indices for bulk screening"}},"type":"object","required":["indices"],"title":"IndicesResponse","example":{"indices":[{"description":"S&P 500 â€” large-cap US equities","estimated_count":503,"name":"SP500"},{"description":"Dow Jones Industrial Average","estimated_count":30,"name":"DJIA"}]}},"KeyUsageResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The API key these stats belong to"},"email":{"type":"string","title":"Email","description":"Email associated with the key"},"plan":{"type":"string","title":"Plan","description":"Current plan tier"},"tokens_used":{"type":"integer","title":"Tokens Used","description":"Tokens consumed this billing period"},"tokens_limit":{"type":"integer","title":"Tokens Limit","description":"Monthly token allowance (-1 = unlimited)"},"requests_used":{"type":"integer","title":"Requests Used","description":"Total requests consumed"},"requests_limit":{"type":"integer","title":"Requests Limit","description":"Maximum requests allowed under the plan"},"billing_period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Period Start","description":"Start of current billing period"},"billing_period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Period End","description":"End of current billing period"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the key is currently active"},"created_at":{"type":"string","title":"Created At","description":"ISO-8601 creation timestamp"},"updated_at":{"type":"string","title":"Updated At","description":"ISO-8601 timestamp of last usage update"},"top_endpoints":{"items":{"$ref":"#/components/schemas/EndpointStat"},"type":"array","title":"Top Endpoints","description":"Most frequently called endpoints","default":[]}},"type":"object","required":["api_key","email","plan","tokens_used","tokens_limit","requests_used","requests_limit","is_active","created_at","updated_at"],"title":"KeyUsageResponse","description":"Detailed usage statistics for an API key.","example":{"api_key":"ht_abc123def456","billing_period_end":"2025-07-01T12:00:00Z","billing_period_start":"2025-06-01T12:00:00Z","created_at":"2025-06-01T12:00:00Z","email":"dev@example.com","is_active":true,"plan":"starter","requests_limit":2500,"requests_used":42,"tokens_limit":2500,"tokens_used":142,"top_endpoints":[{"count":30,"endpoint":"/api/screen","method":"GET","total_tokens":150}],"updated_at":"2025-06-15T08:30:00Z"}},"MethodologiesResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of methodologies available"},"methodologies":{"items":{"$ref":"#/components/schemas/MethodologyDetailResponse"},"type":"array","title":"Methodologies","description":"List of screening methodology details"}},"type":"object","required":["count","methodologies"],"title":"MethodologiesResponse","description":"List of all available Shariah screening methodologies.","example":{"count":2,"methodologies":[{"full_name":"Accounting and Auditing Organization for Islamic Financial Institutions","id":"aaoifi","name":"AAOIFI"},{"full_name":"Securities Commission Malaysia Shariah Advisory Council","id":"sec","name":"SEC Malaysia"}]}},"MethodologyBreakdown":{"properties":{"compliant":{"type":"integer","title":"Compliant","description":"Number of symbols compliant under this methodology"},"non_compliant":{"type":"integer","title":"Non Compliant","description":"Number of symbols non-compliant under this methodology"}},"type":"object","required":["compliant","non_compliant"],"title":"MethodologyBreakdown"},"MethodologyDetailResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Short identifier for the methodology, e.g. 'aaoifi'"},"name":{"type":"string","title":"Name","description":"Common name or abbreviation, e.g. 'AAOIFI'"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"Full official name of the organization"},"established":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Established","description":"Year the organization was established"},"headquarters":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters","description":"City and country of the organization's headquarters"},"basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis","description":"Foundation or basis of the screening methodology"},"overview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overview","description":"General overview of the methodology and its adoption"},"screening_process":{"items":{"type":"string"},"type":"array","title":"Screening Process","description":"Ordered steps in the screening process","default":[]},"thresholds":{"additionalProperties":true,"type":"object","title":"Thresholds","description":"Financial ratio thresholds used in compliance screening","default":{}},"distinguishing_features":{"items":{"type":"string"},"type":"array","title":"Distinguishing Features","description":"Key features that distinguish this methodology from others","default":[]},"shariah_board":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shariah Board","description":"Name of the Shariah supervisory board"},"references":{"items":{"type":"string"},"type":"array","title":"References","description":"Published standards or scholarly references","default":[]}},"type":"object","required":["id","name"],"title":"MethodologyDetailResponse","description":"Detailed information about a Shariah screening methodology.","example":{"basis":"Shariah standards developed by an independent board of scholars","distinguishing_features":["Uses total assets as denominator for financial ratios","Stricter thresholds compared to market-cap-based methodologies"],"established":1991,"full_name":"Accounting and Auditing Organization for Islamic Financial Institutions","headquarters":"Manama, Bahrain","id":"aaoifi","name":"AAOIFI","overview":"AAOIFI sets accounting, auditing, governance, and Shariah standards adopted by Islamic financial institutions in over 45 countries.","references":["AAOIFI Shariah Standard No. 21"],"screening_process":["Business activity screening for haram revenue","Financial ratio screening using total assets as denominator"],"shariah_board":"AAOIFI Shariah Board","thresholds":{"max_debt_to_total_assets":0.3,"max_haram_revenue_percentage":0.05,"max_interest_income_to_revenue":0.05}}},"NewsArticleResponse":{"properties":{"title":{"type":"string","title":"Title","description":"Headline of the news article"},"link":{"type":"string","title":"Link","description":"URL to the full article"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Brief summary or excerpt of the article content"},"published":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published","description":"ISO 8601 publication timestamp"},"source_id":{"type":"string","title":"Source Id","description":"Unique identifier for the news source"},"source_name":{"type":"string","title":"Source Name","description":"Human-readable name of the news source"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Topic category, e.g. 'islamic_finance', 'market', 'regulation'"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url","description":"URL to a thumbnail image for the article"},"sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment","description":"Sentiment label: 'positive', 'negative', or 'neutral'"},"sentiment_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sentiment Score","description":"Numerical sentiment score from -1.0 to 1.0"},"relevance_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Relevance Score","description":"Relevance score from 0.0 to 1.0 indicating how closely the article matches the query"},"freshness_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Freshness Score","description":"Freshness score from 0.0 to 1.0 based on recency of publication"}},"type":"object","required":["title","link","source_id","source_name"],"title":"NewsArticleResponse","description":"A single news article with metadata, sentiment, and scoring.","example":{"category":"islamic_finance","freshness_score":0.88,"link":"https://example.com/articles/aaoifi-sukuk-update","published":"2026-03-20T14:30:00Z","relevance_score":0.95,"sentiment":"positive","sentiment_score":0.72,"source_id":"islamic_finance_news","source_name":"Islamic Finance News","summary":"The Accounting and Auditing Organization for Islamic Financial Institutions has released revised standards for Sukuk structuring.","thumbnail_url":"https://example.com/images/sukuk-thumb.jpg","title":"AAOIFI Updates Shariah Standards for Sukuk Issuance"}},"NewsListResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of articles in the current page"},"page":{"type":"integer","title":"Page","description":"Current page number (1-indexed)"},"page_size":{"type":"integer","title":"Page Size","description":"Maximum number of articles per page"},"total":{"type":"integer","title":"Total","description":"Total number of articles matching the query"},"articles":{"items":{"$ref":"#/components/schemas/NewsArticleResponse"},"type":"array","title":"Articles","description":"List of news articles for this page"}},"type":"object","required":["count","page","page_size","total","articles"],"title":"NewsListResponse","description":"Paginated list of news articles.","example":{"articles":[{"category":"islamic_finance","link":"https://example.com/articles/aaoifi-sukuk-update","published":"2026-03-20T14:30:00Z","sentiment":"positive","sentiment_score":0.72,"source_id":"islamic_finance_news","source_name":"Islamic Finance News","summary":"Revised standards for Sukuk structuring released.","title":"AAOIFI Updates Shariah Standards for Sukuk Issuance"}],"count":2,"page":1,"page_size":20,"total":2}},"NewsSourceResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for the source"},"name":{"type":"string","title":"Name","description":"Display name of the news source"},"url":{"type":"string","title":"Url","description":"RSS feed or API URL for the source"},"category":{"type":"string","title":"Category","description":"Category of the source, e.g. 'islamic_finance', 'market'"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this source is currently active"}},"type":"object","required":["id","name","url","category","enabled"],"title":"NewsSourceResponse","description":"A configured news feed source.","example":{"category":"islamic_finance","enabled":true,"id":"islamic_finance_news","name":"Islamic Finance News","url":"https://www.islamicfinancenews.com/feed"}},"NewsSourcesResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Total number of configured news sources"},"sources":{"items":{"$ref":"#/components/schemas/NewsSourceResponse"},"type":"array","title":"Sources","description":"List of news sources"}},"type":"object","required":["count","sources"],"title":"NewsSourcesResponse","description":"List of all configured news sources.","example":{"count":1,"sources":[{"category":"islamic_finance","enabled":true,"id":"islamic_finance_news","name":"Islamic Finance News","url":"https://www.islamicfinancenews.com/feed"}]}},"OHLCPointResponse":{"properties":{"Date":{"type":"string","title":"Date","description":"Trading date in ISO-8601 format"},"Open":{"type":"number","title":"Open","description":"Opening price"},"High":{"type":"number","title":"High","description":"Highest price during the period"},"Low":{"type":"number","title":"Low","description":"Lowest price during the period"},"Close":{"type":"number","title":"Close","description":"Closing price"},"Volume":{"type":"integer","title":"Volume","description":"Number of shares traded"}},"type":"object","required":["Date","Open","High","Low","Close","Volume"],"title":"OHLCPointResponse","example":{"Close":187.44,"Date":"2025-03-21","High":188.5,"Low":185.73,"Open":186.12,"Volume":54638921}},"PlanInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Machine-readable plan identifier"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable plan name"},"price_monthly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Monthly","description":"Monthly price in USD, null for free tier"},"tokens_limit":{"type":"integer","title":"Tokens Limit","description":"Monthly token allowance (-1 = unlimited)"},"requests_limit":{"type":"integer","title":"Requests Limit","description":"Monthly API request quota"},"overage_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overage Rate","description":"Per-token overage rate in USD, null if no overage"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"List of features included in this plan"},"is_popular":{"type":"boolean","title":"Is Popular","description":"Whether to highlight this plan in the UI","default":false}},"type":"object","required":["name","display_name","tokens_limit","requests_limit","features"],"title":"PlanInfo","description":"Details of an available API subscription plan.","example":{"display_name":"Starter","features":["2,500 tokens/mo","All endpoints","Email support"],"is_popular":false,"name":"starter","overage_rate":0.01,"price_monthly":19,"requests_limit":2500,"tokens_limit":2500}},"PlansResponse":{"properties":{"plans":{"items":{"$ref":"#/components/schemas/PlanInfo"},"type":"array","title":"Plans","description":"Available API subscription plans"}},"type":"object","required":["plans"],"title":"PlansResponse","description":"List of all available API plans.","example":{"plans":[{"display_name":"Free","features":["500 tokens for testing"],"is_popular":false,"name":"free","requests_limit":50,"tokens_limit":500}]}},"PortalRequest":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"API key whose subscription should be managed"}},"type":"object","required":["api_key"],"title":"PortalRequest","description":"Request body for creating a Stripe Customer Portal session.","example":{"api_key":"ht_abc123def456"}},"PortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url","description":"URL of the Stripe Customer Portal session"}},"type":"object","required":["portal_url"],"title":"PortalResponse","description":"Response with a Stripe Customer Portal URL.","example":{"portal_url":"https://billing.stripe.com/p/session/test_xyz"}},"PortfolioHoldingReport":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the holding"},"is_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Compliant","description":"Whether the holding passes Shariah compliance screening; null if an error occurred"},"screening":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Screening","description":"Detailed screening results, if available"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if screening could not be completed for this holding"}},"additionalProperties":true,"type":"object","required":["symbol"],"title":"PortfolioHoldingReport","description":"Screening result for a single holding within a portfolio report.","example":{"is_compliant":true,"screening":{"business_screening":{"passed":true},"financial_screening":{"passed":true},"methodology":"aaoifi"},"symbol":"AAPL"}},"PortfolioReportRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols","description":"List of ticker symbols to include in the portfolio report"}},"type":"object","required":["symbols"],"title":"PortfolioReportRequest","description":"Request body for generating a portfolio-level compliance report.","example":{"symbols":["AAPL","MSFT","AMZN"]}},"PortfolioReportResponse":{"properties":{"report_generated_at":{"type":"string","title":"Report Generated At","description":"ISO 8601 timestamp when the report was generated"},"total":{"type":"integer","title":"Total","description":"Total number of holdings analyzed"},"compliant":{"type":"integer","title":"Compliant","description":"Number of holdings that passed Shariah compliance screening"},"non_compliant":{"type":"integer","title":"Non Compliant","description":"Number of holdings that failed Shariah compliance screening"},"errors":{"type":"integer","title":"Errors","description":"Number of holdings where screening could not be completed"},"compliance_percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compliance Percentage","description":"Percentage of successfully screened holdings that are compliant"},"holdings":{"items":{"$ref":"#/components/schemas/PortfolioHoldingReport"},"type":"array","title":"Holdings","description":"Individual screening results for each holding in the portfolio"}},"type":"object","required":["report_generated_at","total","compliant","non_compliant","errors","holdings"],"title":"PortfolioReportResponse","description":"Aggregated Shariah compliance report for a portfolio of stocks.","example":{"compliance_percentage":66.67,"compliant":2,"errors":0,"holdings":[{"is_compliant":true,"screening":{"methodology":"aaoifi"},"symbol":"AAPL"},{"is_compliant":true,"screening":{"methodology":"aaoifi"},"symbol":"MSFT"},{"is_compliant":false,"screening":{"methodology":"aaoifi"},"symbol":"AMZN"}],"non_compliant":1,"report_generated_at":"2026-03-24T12:00:00Z","total":3}},"PortfolioScanRequest":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Symbols","description":"List of ticker symbols to screen (e.g. ['AAPL', 'MSFT', 'GOOGL'])."},"force_refresh":{"type":"boolean","title":"Force Refresh","description":"When true, bypass cached screening results and re-screen from scratch.","default":false}},"type":"object","required":["symbols"],"title":"PortfolioScanRequest","description":"Request to scan a portfolio of stock symbols for Shariah compliance.","example":{"force_refresh":false,"symbols":["AAPL","MSFT","GOOGL"]}},"PortfolioScanResponse":{"properties":{"results":{"additionalProperties":{"$ref":"#/components/schemas/ScreeningResultResponse"},"type":"object","title":"Results","description":"Mapping of ticker symbol to its screening result."},"summary":{"$ref":"#/components/schemas/PortfolioSummaryResponse","description":"Aggregate compliance statistics for the portfolio."}},"type":"object","required":["results","summary"],"title":"PortfolioScanResponse","description":"Full portfolio scan result with per-symbol details and summary statistics.","example":{"results":{"AAPL":{"compliance_status":"compliant","name":"Apple Inc.","purification_rate":0.025,"symbol":"AAPL"},"MSFT":{"compliance_status":"compliant","name":"Microsoft Corp.","purification_rate":0.031,"symbol":"MSFT"}},"summary":{"avg_purification_rate":0.028,"compliant":2,"non_compliant":0,"pending":0,"total":2}}},"PortfolioSummaryResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of symbols scanned."},"compliant":{"type":"integer","title":"Compliant","description":"Number of Shariah-compliant symbols."},"non_compliant":{"type":"integer","title":"Non Compliant","description":"Number of non-compliant symbols."},"pending":{"type":"integer","title":"Pending","description":"Number of symbols still pending screening (data unavailable)."},"avg_purification_rate":{"type":"number","title":"Avg Purification Rate","description":"Average purification rate across all screened holdings (e.g. 0.03 = 3%)."}},"type":"object","required":["total","compliant","non_compliant","pending","avg_purification_rate"],"title":"PortfolioSummaryResponse","description":"Aggregate compliance statistics for a portfolio scan.","example":{"avg_purification_rate":0.028,"compliant":2,"non_compliant":1,"pending":0,"total":3}},"PurificationCalculateRequest":{"properties":{"holdings":{"items":{"$ref":"#/components/schemas/PurificationHolding"},"type":"array","title":"Holdings","description":"List of holdings with dividend income to purify."}},"type":"object","required":["holdings"],"title":"PurificationCalculateRequest","description":"Request to calculate dividend purification amounts for a set of holdings.","example":{"holdings":[{"dividend_income":320.0,"symbol":"MSFT"},{"dividend_income":150.0,"symbol":"AAPL"}]}},"PurificationCalculateResponse":{"properties":{"total_dividend_income":{"type":"number","title":"Total Dividend Income","description":"Sum of all dividend income in USD."},"total_purification":{"type":"number","title":"Total Purification","description":"Total amount to purify across all holdings in USD."},"total_halal":{"type":"number","title":"Total Halal","description":"Total halal dividend amount after purification in USD."},"holdings":{"items":{"$ref":"#/components/schemas/PurificationHoldingResult"},"type":"array","title":"Holdings","description":"Per-holding purification details."}},"type":"object","required":["total_dividend_income","total_purification","total_halal","holdings"],"title":"PurificationCalculateResponse","description":"Aggregate purification calculation across all holdings.","example":{"holdings":[{"dividend_income":320.0,"halal_amount":310.08,"is_compliant":true,"purification_amount":9.92,"purification_rate":0.031,"symbol":"MSFT"},{"dividend_income":150.0,"halal_amount":146.25,"is_compliant":true,"purification_amount":3.75,"purification_rate":0.025,"symbol":"AAPL"}],"total_dividend_income":470.0,"total_halal":456.33,"total_purification":13.67}},"PurificationGuideResponse":{"properties":{"overview":{"additionalProperties":true,"type":"object","title":"Overview","description":"General overview of the purification concept","default":{}},"purification_formula":{"additionalProperties":true,"type":"object","title":"Purification Formula","description":"Formula and methodology for calculating the amount to purify","default":{}},"capital_gains_purification":{"additionalProperties":true,"type":"object","title":"Capital Gains Purification","description":"Guidance on purification of capital gains from stock sales","default":{}},"zakat_on_investments":{"additionalProperties":true,"type":"object","title":"Zakat On Investments","description":"Zakat calculation guidance for investment portfolios","default":{}},"scholarly_references":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Scholarly References","description":"Scholarly sources and standards referenced in the guide","default":[]}},"additionalProperties":true,"type":"object","title":"PurificationGuideResponse","description":"Guide for purifying investment returns from non-compliant income.","example":{"capital_gains_purification":{"description":"Scholars differ on whether capital gains require purification."},"overview":{"description":"Purification is the process of cleansing investment returns from haram income by donating a proportional amount to charity."},"purification_formula":{"description":"Calculate the impure portion of dividends received and donate it.","formula":"(Haram Revenue / Total Revenue) x Dividend Received"},"scholarly_references":[{"source":"AAOIFI Shariah Standard No. 21","topic":"Purification of unlawful income"}],"zakat_on_investments":{"description":"2.5% annual zakat on qualifying investment holdings.","rate":0.025}}},"PurificationHolding":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol (e.g. 'AAPL')."},"dividend_income":{"type":"number","minimum":0.0,"title":"Dividend Income","description":"Dividend income received from this holding in USD."}},"type":"object","required":["symbol","dividend_income"],"title":"PurificationHolding","description":"A stock holding with dividend income for purification calculation.","example":{"dividend_income":320.0,"symbol":"MSFT"}},"PurificationHoldingResult":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol."},"dividend_income":{"type":"number","title":"Dividend Income","description":"Dividend income in USD."},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Company-specific purification rate (e.g. 0.031 = 3.1%). Null if unknown."},"purification_amount":{"type":"number","title":"Purification Amount","description":"Dollar amount to purify (donate) from this holding's dividends."},"halal_amount":{"type":"number","title":"Halal Amount","description":"Remaining halal dividend amount after purification."},"is_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Compliant","description":"Whether the holding is Shariah-compliant. Null if unscreened."}},"type":"object","required":["symbol","dividend_income","purification_amount","halal_amount"],"title":"PurificationHoldingResult","description":"Purification result for a single holding.","example":{"dividend_income":320.0,"halal_amount":310.08,"is_compliant":true,"purification_amount":9.92,"purification_rate":0.031,"symbol":"MSFT"}},"PurifiedDividend":{"properties":{"date":{"type":"string","title":"Date","description":"Payment date in YYYY-MM-DD format."},"amount":{"type":"number","title":"Amount","description":"Original dividend amount per share in USD."},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Purification rate applied to this dividend (e.g. 0.031 = 3.1%)."},"purification_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Amount","description":"Dollar amount to purify (donate) from this dividend."},"halal_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Halal Amount","description":"Remaining halal amount after purification."}},"type":"object","required":["date","amount"],"title":"PurifiedDividend","description":"A dividend payment with purification details applied.","example":{"amount":0.83,"date":"2025-12-11","halal_amount":0.804,"purification_amount":0.026,"purification_rate":0.031}},"QuoteResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"name":{"type":"string","title":"Name","description":"Company or asset name"},"price":{"type":"number","title":"Price","description":"Last traded price in USD"},"change":{"type":"number","title":"Change","description":"Absolute price change since previous close"},"changePercent":{"type":"number","title":"Changepercent","description":"Percentage price change since previous close"},"volume":{"type":"integer","title":"Volume","description":"Trading volume for the current session"},"high":{"type":"number","title":"High","description":"Session high price"},"low":{"type":"number","title":"Low","description":"Session low price"},"open":{"type":"number","title":"Open","description":"Session opening price"},"previousClose":{"type":"number","title":"Previousclose","description":"Previous session closing price"},"marketCap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Marketcap","description":"Market capitalization in USD"},"peRatio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peratio","description":"Price-to-earnings ratio (trailing twelve months)"},"dividendYield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividendyield","description":"Annual dividend yield as a decimal"},"beta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Beta","description":"Beta coefficient relative to the market"}},"type":"object","required":["symbol","name","price","change","changePercent","volume","high","low","open","previousClose"],"title":"QuoteResponse","example":{"beta":1.28,"change":1.32,"changePercent":0.71,"dividendYield":0.0055,"high":188.5,"low":185.73,"marketCap":2890000000000,"name":"Apple Inc.","open":186.12,"peRatio":29.5,"previousClose":186.12,"price":187.44,"symbol":"AAPL","volume":54638921}},"RecentRequestEntry":{"properties":{"endpoint":{"type":"string","title":"Endpoint","description":"API endpoint that was called"},"method":{"type":"string","title":"Method","description":"HTTP method used"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"HTTP status code returned"},"tokens_charged":{"type":"integer","title":"Tokens Charged","description":"Tokens charged for this request","default":0},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the request"}},"type":"object","required":["endpoint","method","timestamp"],"title":"RecentRequestEntry","description":"A single recent API request log entry.","example":{"endpoint":"/api/screen","method":"GET","status_code":200,"timestamp":"2025-06-15T14:32:00Z","tokens_charged":5}},"RecentRequestsResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The API key these requests belong to"},"requests":{"items":{"$ref":"#/components/schemas/RecentRequestEntry"},"type":"array","title":"Requests","description":"Recent API request log entries"}},"type":"object","required":["api_key","requests"],"title":"RecentRequestsResponse","description":"List of the most recent API requests for a key.","example":{"api_key":"ht_abc123def456","requests":[{"endpoint":"/api/screen","method":"GET","status_code":200,"timestamp":"2025-06-15T14:32:00Z","tokens_charged":5}]}},"RegenerateKeyResponse":{"properties":{"old_key":{"type":"string","title":"Old Key","description":"The deactivated API key"},"new_key":{"type":"string","title":"New Key","description":"The newly generated replacement key"},"email":{"type":"string","title":"Email","description":"Email associated with the key"},"plan":{"type":"string","title":"Plan","description":"Plan tier carried over to the new key"}},"type":"object","required":["old_key","new_key","email","plan"],"title":"RegenerateKeyResponse","description":"Response returned after regenerating an API key.","example":{"email":"dev@example.com","new_key":"ht_xyz789ghi012","old_key":"ht_abc123def456","plan":"starter"}},"RevokeKeyRequest":{"properties":{"key_prefix":{"type":"string","title":"Key Prefix","description":"Public 10-char prefix (e.g. ht_abc12345)"}},"type":"object","required":["key_prefix"],"title":"RevokeKeyRequest","description":"Internal-only: revoke a key by its public prefix."},"RunHistoryItem":{"properties":{"run_id":{"type":"string","title":"Run Id"},"index_name":{"type":"string","title":"Index Name"},"status":{"type":"string","title":"Status"},"total":{"type":"integer","title":"Total"},"done":{"type":"integer","title":"Done"},"failed_count":{"type":"integer","title":"Failed Count","default":0},"compliance_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compliance Rate","description":"Overall compliance rate for this run (available after completion)"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds"}},"additionalProperties":true,"type":"object","required":["run_id","index_name","status","total","done"],"title":"RunHistoryItem"},"RunHistoryResponse":{"properties":{"runs":{"items":{"$ref":"#/components/schemas/RunHistoryItem"},"type":"array","title":"Runs"},"total_runs":{"type":"integer","title":"Total Runs"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"}},"type":"object","required":["runs","total_runs","page","page_size"],"title":"RunHistoryResponse","example":{"page":1,"page_size":20,"runs":[{"compliance_rate":62.03,"created_at":"2025-01-15T08:00:00Z","done":503,"duration_seconds":765,"failed_count":3,"finished_at":"2025-01-15T08:12:45Z","index_name":"SP500","run_id":"run_2025-01-15_sp500","status":"completed","total":503}],"total_runs":1}},"RunResultsResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"index_name":{"type":"string","title":"Index Name"},"total_results":{"type":"integer","title":"Total Results","description":"Total number of results matching the applied filters"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"results":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Results","description":"List of per-symbol screening result dictionaries"}},"additionalProperties":true,"type":"object","required":["run_id","index_name","total_results","page","page_size","results"],"title":"RunResultsResponse","example":{"index_name":"SP500","page":1,"page_size":50,"results":[{"is_compliant":true,"purification_rate":0.012,"sector":"Technology","symbol":"AAPL"}],"run_id":"run_2025-01-15_sp500","total_results":503}},"RunSummaryOverall":{"properties":{"compliant":{"type":"integer","title":"Compliant"},"non_compliant":{"type":"integer","title":"Non Compliant"},"errors":{"type":"integer","title":"Errors"},"compliance_rate":{"type":"number","title":"Compliance Rate","description":"Overall compliance rate as a percentage"}},"type":"object","required":["compliant","non_compliant","errors","compliance_rate"],"title":"RunSummaryOverall"},"RunSummaryResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"index_name":{"type":"string","title":"Index Name"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds","description":"Wall-clock time in seconds from start to finish"},"total_screened":{"type":"integer","title":"Total Screened"},"overall":{"$ref":"#/components/schemas/RunSummaryOverall"},"by_methodology":{"additionalProperties":{"$ref":"#/components/schemas/MethodologyBreakdown"},"type":"object","title":"By Methodology","description":"Compliance breakdown per screening methodology"},"by_sector":{"additionalProperties":{"$ref":"#/components/schemas/SectorBreakdown"},"type":"object","title":"By Sector","description":"Compliance breakdown per GICS sector"},"top_compliant":{"items":{"$ref":"#/components/schemas/TopCompliantItem"},"type":"array","title":"Top Compliant","description":"Top compliant symbols ranked by number of passing methodologies"}},"type":"object","required":["run_id","index_name","total_screened","overall","by_methodology","by_sector","top_compliant"],"title":"RunSummaryResponse","example":{"by_methodology":{"aaoifi":{"compliant":298,"non_compliant":199},"djim":{"compliant":334,"non_compliant":163}},"by_sector":{"Healthcare":{"compliance_rate":65.08,"compliant":41,"total":63},"Technology":{"compliance_rate":66.67,"compliant":52,"total":78}},"completed_at":"2025-01-15T08:12:45Z","duration_seconds":765,"index_name":"SP500","overall":{"compliance_rate":62.03,"compliant":312,"errors":6,"non_compliant":185},"run_id":"run_2025-01-15_sp500","top_compliant":[{"methodology_count":5,"purification_rate":0.012,"symbol":"AAPL"},{"methodology_count":5,"purification_rate":0.008,"symbol":"MSFT"}],"total_screened":503}},"SECFilingResponse":{"properties":{"accession_number":{"type":"string","title":"Accession Number","description":"SEC EDGAR accession number uniquely identifying the filing"},"filing_type":{"type":"string","title":"Filing Type","description":"SEC form type, e.g. '10-K', '10-Q', '8-K', 'DEF 14A'"},"filing_date":{"type":"string","title":"Filing Date","description":"Date the filing was submitted (YYYY-MM-DD)"},"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document","description":"Filename of the primary document in the filing"},"primary_doc_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Doc Description","description":"Human-readable description of the primary document"},"filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Url","description":"Direct URL to view the filing on SEC EDGAR"}},"type":"object","required":["accession_number","filing_type","filing_date"],"title":"SECFilingResponse","description":"A single SEC filing record.","example":{"accession_number":"0000320193-23-000106","filing_date":"2023-11-03","filing_type":"10-K","filing_url":"https://www.sec.gov/Archives/edgar/data/320193/000032019323000106/aapl-20230930.htm","primary_doc_description":"10-K Annual Report","primary_document":"aapl-20230930.htm"}},"ScreeningCriteriaResponse":{"properties":{"business_screening":{"additionalProperties":true,"type":"object","title":"Business Screening","description":"Criteria for screening a company's core business activities against prohibited sectors","default":{}},"financial_screening":{"additionalProperties":true,"type":"object","title":"Financial Screening","description":"Financial ratio thresholds for debt, interest income, and cash holdings","default":{}}},"additionalProperties":true,"type":"object","title":"ScreeningCriteriaResponse","description":"Business and financial screening criteria used for Shariah compliance.","example":{"business_screening":{"max_haram_revenue_percentage":0.05,"prohibited_sectors":["Conventional banking and insurance","Alcohol production and distribution","Pork-related products","Gambling and entertainment","Tobacco","Weapons and defense"]},"financial_screening":{"max_cash_and_interest_bearing_to_total_assets":0.3,"max_debt_to_total_assets":0.3,"max_interest_income_to_revenue":0.05}}},"ScreeningReportResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol of the screened company"},"report_generated_at":{"type":"string","title":"Report Generated At","description":"ISO 8601 timestamp when the report was generated"},"screening":{"additionalProperties":true,"type":"object","title":"Screening","description":"Detailed screening results including business and financial ratio checks"}},"additionalProperties":true,"type":"object","required":["symbol","report_generated_at","screening"],"title":"ScreeningReportResponse","description":"Full Shariah compliance screening report for a single stock.","example":{"report_generated_at":"2026-03-24T12:00:00Z","screening":{"business_screening":{"haram_revenue_percentage":0.02,"passed":true},"financial_screening":{"debt_to_total_assets":0.25,"interest_income_to_revenue":0.01,"passed":true},"is_compliant":true,"methodology":"aaoifi"},"symbol":"AAPL"}},"ScreeningResultResponse":{"properties":{"symbol":{"type":"string","title":"Symbol"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Last Checked At"},"is_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Compliant","description":"Overall Shariah compliance verdict (True = compliant under at least one methodology)"},"business_screen_pass":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Business Screen Pass","description":"Whether the company's primary business activities are permissible"},"business_screen_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Screen Reason","description":"Human-readable explanation for the business screen verdict"},"financial_screen_pass":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Financial Screen Pass","description":"Whether the company passes all financial ratio thresholds"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"long_business_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Long Business Summary"},"total_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Assets"},"total_debt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Debt"},"cash_and_equivalents":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash And Equivalents"},"accounts_receivable":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Accounts Receivable"},"total_revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Revenue"},"interest_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interest Income"},"debt_to_assets_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Assets Ratio","description":"Total debt / total assets â€” must be below threshold (e.g. 33% for AAOIFI)"},"cash_to_assets_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash To Assets Ratio","description":"Cash and equivalents / total assets"},"accounts_receivable_to_assets_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Accounts Receivable To Assets Ratio","description":"Accounts receivable / total assets"},"interest_income_to_revenue_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interest Income To Revenue Ratio","description":"Interest income / total revenue â€” measures impermissible income proportion"},"debt_to_market_cap_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Market Cap Ratio","description":"Total debt / market capitalization (used by DJIM, S&P methodologies)"},"cash_to_market_cap_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash To Market Cap Ratio"},"liquidity_to_market_cap_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Liquidity To Market Cap Ratio"},"liquidity_to_assets_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Liquidity To Assets Ratio"},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Percentage of dividend income to purify (donate) due to impermissible revenue"},"aaoifi_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Aaoifi Compliant","description":"Compliance under AAOIFI (Accounting and Auditing Organization for Islamic Financial Institutions) standards"},"djim_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Djim Compliant","description":"Compliance under Dow Jones Islamic Market Index methodology"},"ftse_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ftse Compliant","description":"Compliance under FTSE Shariah Index methodology"},"msci_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Msci Compliant","description":"Compliance under MSCI Islamic Index methodology"},"sp_compliant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sp Compliant","description":"Compliance under S&P Shariah Index methodology"},"methodology_summary":{"anyOf":[{"additionalProperties":{"type":"boolean"},"type":"object"},{"type":"null"}],"title":"Methodology Summary","description":"Mapping of methodology name to compliance boolean"},"return_on_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Return On Equity"},"net_profit_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Profit Margin"},"revenue_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth"},"pe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe Ratio"},"pb_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pb Ratio"},"intrinsic_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intrinsic Value"},"dcf_upside_percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dcf Upside Percentage","description":"Upside/downside percentage based on DCF intrinsic value vs current price"},"momentum_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Momentum Trend"},"rsi_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rsi Status"},"current_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Ratio"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"beta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Beta"},"dividend_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Yield"}},"additionalProperties":true,"type":"object","required":["symbol"],"title":"ScreeningResultResponse","example":{"aaoifi_compliant":true,"accounts_receivable":60932000000,"accounts_receivable_to_assets_ratio":0.173,"business_screen_pass":true,"business_screen_reason":"Technology hardware and equipment â€” permissible primary activity","cash_and_equivalents":29965000000,"cash_to_assets_ratio":0.085,"cash_to_market_cap_ratio":0.009,"country":"US","debt_to_assets_ratio":0.315,"debt_to_market_cap_ratio":0.032,"djim_compliant":true,"financial_screen_pass":true,"ftse_compliant":true,"industry":"Consumer Electronics","interest_income":3999000000,"interest_income_to_revenue_ratio":0.01,"is_compliant":true,"last_checked_at":"2025-01-15T12:30:00Z","methodology_summary":{"aaoifi":true,"djim":true,"ftse":true,"msci":true,"sp":true},"msci_compliant":true,"purification_rate":0.012,"sector":"Technology","sp_compliant":true,"symbol":"AAPL","total_assets":352583000000,"total_debt":111088000000,"total_revenue":394328000000}},"SectorBreakdown":{"properties":{"total":{"type":"integer","title":"Total"},"compliant":{"type":"integer","title":"Compliant"},"compliance_rate":{"type":"number","title":"Compliance Rate","description":"Percentage of compliant symbols in this sector (0.0 to 100.0)"}},"type":"object","required":["total","compliant","compliance_rate"],"title":"SectorBreakdown"},"SuggestionResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"name":{"type":"string","title":"Name","description":"Company or asset name"},"sector":{"type":"string","title":"Sector","description":"Sector classification"},"exchange":{"type":"string","title":"Exchange","description":"Exchange where the asset is listed"},"type":{"type":"string","title":"Type","description":"Asset type, e.g. equities, etfs, funds"}},"type":"object","required":["symbol","name","sector","exchange","type"],"title":"SuggestionResponse","example":{"exchange":"NMS","name":"Apple Inc.","sector":"Technology","symbol":"AAPL","type":"equities"}},"TokenCostEntry":{"properties":{"pattern":{"type":"string","title":"Pattern","description":"Endpoint path pattern"},"method":{"type":"string","title":"Method","description":"HTTP method (* = all methods)"},"tokens":{"type":"integer","title":"Tokens","description":"Token cost per request"}},"type":"object","required":["pattern","method","tokens"],"title":"TokenCostEntry","description":"Token cost for an endpoint pattern.","example":{"method":"GET","pattern":"/api/screen","tokens":5}},"TokenCostsResponse":{"properties":{"costs":{"items":{"$ref":"#/components/schemas/TokenCostEntry"},"type":"array","title":"Costs","description":"Token costs per endpoint"}},"type":"object","required":["costs"],"title":"TokenCostsResponse","description":"Full token cost table.","example":{"costs":[{"method":"*","pattern":"/api/health","tokens":0},{"method":"GET","pattern":"/api/screen","tokens":5}]}},"TopCompliantItem":{"properties":{"symbol":{"type":"string","title":"Symbol"},"purification_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Purification Rate","description":"Dividend purification rate for this symbol"},"methodology_count":{"type":"integer","title":"Methodology Count","description":"Number of methodologies under which this symbol is compliant","default":0}},"type":"object","required":["symbol"],"title":"TopCompliantItem"},"TrendingItemResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol"},"name":{"type":"string","title":"Name","description":"Company or asset name"},"change":{"type":"string","title":"Change","description":"Price change as a formatted string"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Current price in USD"},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Trading volume for the current session"}},"type":"object","required":["symbol","name","change"],"title":"TrendingItemResponse","example":{"change":"+1.25%","name":"Apple Inc.","price":187.44,"symbol":"AAPL","volume":54638921}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WatchlistCreateRequest":{"properties":{"name":{"type":"string","title":"Name","description":"Display name for the watchlist"},"symbols":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Symbols","description":"Initial list of stock ticker symbols to include"}},"type":"object","required":["name"],"title":"WatchlistCreateRequest","description":"Request body for creating a new watchlist.","example":{"name":"Halal Tech","symbols":["AAPL","MSFT","GOOGL"]}},"WatchlistResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique watchlist identifier"},"name":{"type":"string","title":"Name","description":"Display name of the watchlist"},"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols","description":"Ticker symbols in the watchlist"},"count":{"type":"integer","title":"Count","description":"Number of symbols currently in the watchlist"},"created_at":{"type":"string","title":"Created At","description":"ISO-8601 timestamp when the watchlist was created"},"updated_at":{"type":"string","title":"Updated At","description":"ISO-8601 timestamp of the last modification"}},"additionalProperties":true,"type":"object","required":["id","name","symbols","count","created_at","updated_at"],"title":"WatchlistResponse","description":"Representation of a watchlist with its symbols and metadata.","example":{"count":3,"created_at":"2025-06-01T12:00:00Z","id":"wl_abc123","name":"Halal Tech","symbols":["AAPL","MSFT","GOOGL"],"updated_at":"2025-06-01T12:00:00Z"}},"WatchlistSymbolRequest":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Stock ticker symbol to add (e.g. AAPL)"}},"type":"object","required":["symbol"],"title":"WatchlistSymbolRequest","description":"Request body for adding a single symbol to an existing watchlist.","example":{"symbol":"AMZN"}},"ZakatCalculateRequest":{"properties":{"holdings":{"items":{"$ref":"#/components/schemas/ZakatHolding"},"type":"array","title":"Holdings","description":"List of stock holdings with current market values."},"gold_price_per_gram":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Gold Price Per Gram","description":"Current gold price per gram in USD, used to compute the nisab threshold. If omitted, live gold price is fetched automatically."}},"type":"object","required":["holdings"],"title":"ZakatCalculateRequest","description":"Request to calculate zakat owed on a set of stock holdings.","example":{"gold_price_per_gram":65.0,"holdings":[{"market_value":25000.0,"symbol":"AAPL"},{"market_value":18000.0,"symbol":"MSFT"},{"market_value":12000.0,"symbol":"GOOGL"}]}},"ZakatCalculateResponse":{"properties":{"total_market_value":{"type":"number","title":"Total Market Value","description":"Total market value of all holdings in USD."},"nisab_threshold":{"type":"number","title":"Nisab Threshold","description":"Nisab threshold in USD (85 grams of gold at given price)."},"gold_price_per_gram":{"type":"number","title":"Gold Price Per Gram","description":"Gold price per gram used for nisab calculation."},"is_above_nisab":{"type":"boolean","title":"Is Above Nisab","description":"Whether total holdings exceed the nisab threshold."},"zakat_rate":{"type":"number","title":"Zakat Rate","description":"Zakat rate applied (0.025 = 2.5%)."},"total_zakat":{"type":"number","title":"Total Zakat","description":"Total zakat owed across all holdings in USD. Zero if below nisab."},"holdings":{"items":{"$ref":"#/components/schemas/ZakatHoldingResult"},"type":"array","title":"Holdings","description":"Per-holding zakat breakdown."}},"type":"object","required":["total_market_value","nisab_threshold","gold_price_per_gram","is_above_nisab","zakat_rate","total_zakat","holdings"],"title":"ZakatCalculateResponse","description":"Complete zakat calculation result with nisab check and per-holding breakdown.","example":{"gold_price_per_gram":65.0,"holdings":[{"market_value":25000.0,"symbol":"AAPL","zakat_amount":625.0},{"market_value":18000.0,"symbol":"MSFT","zakat_amount":450.0},{"market_value":12000.0,"symbol":"GOOGL","zakat_amount":300.0}],"is_above_nisab":true,"nisab_threshold":5525.0,"total_market_value":55000.0,"total_zakat":1375.0,"zakat_rate":0.025}},"ZakatHolding":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol (e.g. 'AAPL')."},"market_value":{"type":"number","minimum":0.0,"title":"Market Value","description":"Current market value of the holding in USD."}},"type":"object","required":["symbol","market_value"],"title":"ZakatHolding","description":"A single stock holding for zakat calculation.","example":{"market_value":25000.0,"symbol":"AAPL"}},"ZakatHoldingResult":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Ticker symbol."},"market_value":{"type":"number","title":"Market Value","description":"Market value of the holding in USD."},"zakat_amount":{"type":"number","title":"Zakat Amount","description":"Zakat owed on this holding in USD (2.5% of value)."}},"type":"object","required":["symbol","market_value","zakat_amount"],"title":"ZakatHoldingResult","description":"Zakat calculation result for a single holding.","example":{"market_value":25000.0,"symbol":"AAPL","zakat_amount":625.0}},"backend__schemas__comparison__CompareResponse":{"properties":{"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols","description":"Symbols that were compared"},"count":{"type":"integer","title":"Count","description":"Number of symbols in the comparison"},"items":{"items":{"$ref":"#/components/schemas/CompareItemResponse"},"type":"array","title":"Items","description":"Per-symbol comparison results"}},"additionalProperties":true,"type":"object","required":["symbols","count","items"],"title":"CompareResponse","description":"Aggregated comparison result for the requested symbols.","example":{"count":2,"items":[{"database":{"sector":"Technology"},"quote":{"price":198.5},"screening":{"status":"COMPLIANT"},"symbol":"AAPL"},{"database":{"sector":"Technology"},"quote":{"price":415.2},"screening":{"status":"COMPLIANT"},"symbol":"MSFT"}],"symbols":["AAPL","MSFT"]}},"backend__schemas__screening__CompareResponse":{"properties":{"run_a":{"type":"string","title":"Run A"},"run_b":{"type":"string","title":"Run B"},"index_name":{"type":"string","title":"Index Name"},"run_a_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run A Date"},"run_b_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run B Date"},"summary":{"$ref":"#/components/schemas/CompareSummary"},"changes":{"items":{"$ref":"#/components/schemas/CompareChange"},"type":"array","title":"Changes"}},"type":"object","required":["run_a","run_b","index_name","summary","changes"],"title":"CompareResponse","example":{"changes":[{"change":"became_compliant","reason":"Debt-to-assets ratio dropped below 33% threshold","run_a_compliant":false,"run_b_compliant":true,"symbol":"TSLA"}],"index_name":"SP500","run_a":"run_2025-01-01_sp500","run_a_date":"2025-01-01T08:00:00Z","run_b":"run_2025-01-15_sp500","run_b_date":"2025-01-15T08:00:00Z","summary":{"added_symbols":2,"newly_compliant":8,"newly_non_compliant":5,"removed_symbols":1,"unchanged_compliant":304,"unchanged_non_compliant":180}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your Halal Terminal API key. Get one free at /api/keys/generate"}}},"tags":[{"name":"health","description":"Health-check and liveness probes â€” no API key required"},{"name":"screening","description":"Single-symbol and bulk Shariah screening across AAOIFI and custom methodologies"},{"name":"database","description":"Stock database search, autocomplete suggestions, and coverage statistics"},{"name":"market","description":"Real-time quotes, OHLC candles, trending tickers, and full asset details"},{"name":"portfolio","description":"Portfolio-level compliance scanning with position weighting"},{"name":"watchlists","description":"Create, update, and manage personal watchlists"},{"name":"comparison","description":"Side-by-side Shariah compliance comparison for multiple symbols"},{"name":"reports","description":"Generate screening and portfolio compliance reports with CSV export"},{"name":"education","description":"Islamic finance glossary, screening methodologies, and criteria reference"},{"name":"news","description":"Market-wide and per-symbol news aggregation"},{"name":"filings","description":"SEC filings (10-K, 10-Q) and XBRL company facts"},{"name":"dividends","description":"Dividend history, yield data, and Shariah purification calculations"},{"name":"zakat","description":"Zakat and dividend purification calculators"},{"name":"etf","description":"ETF holdings retrieval, per-holding Shariah screening, and purification ratios"},{"name":"api-keys","description":"API key generation, usage tracking, and plan management â€” no API key required"},{"name":"billing","description":"Stripe checkout sessions and webhook handling â€” no API key required"}],"security":[{"ApiKeyAuth":[]}]}