> ## Documentation Index > Fetch the complete documentation index at: https://docs.halal.sh/llms.txt > Use this file to discover all available pages before exploring further. # Screen Instruments > Screen stocks in one request. Provide either: - `symbols` — up to 50 specific stock tickers (available on every plan), or - filters (`status`, `sector`, `market_cap`, `health`) to discover matching stocks across the universe (requires the Plus plan). This endpoint screens **equities**. ETF tickers don't resolve here — they are returned in `meta.not_found`; use `GET /etfs/{symbol}` for funds. Returns `200` with an empty array when nothing matches. ## OpenAPI ````yaml POST /screen openapi: 3.1.0 info: title: halal.sh API version: 1.0.0 description: > The halal.sh API provides Shariah compliance screening for public equities and ETFs, based on AAOIFI Shari'ah Standard No. 21. Unlike a black-box verdict, every determination exposes the individual screens, the financial ratios with their thresholds, the revenue breakdown, and the source filings behind each number. The Evidence Packet endpoint returns the full audit trail — accession numbers, XBRL tags, and extraction strategies — for compliance, reporting, and reproducibility. ## Conventions - **Base URL** — `https://api.halal.sh/v1` - **Authentication** — send your key in the `X-API-Key` header. - **Envelope** — every success response is `{ "data": …, "meta": … }`. Every error is `{ "error": { "code", "message" } }`. - **Ratios** — screen `value`, `threshold`, and `buffer` are decimals (`0.082` means 8.2%, `0.30` means 30%). Fields named `*percentage`, `purity.percentage`, and holding `weight` are whole-number percentages (`66.74` means 66.74%). Each field documents its unit. - **Status** — compliance status is always `compliant`, `non-compliant`, or `pending`. Treat unknown future values as `pending`. - **Money** — values are in the instrument's reporting currency (USD for US filers). contact: name: halal.sh API support url: https://halal.sh/developers email: api@halal.sh servers: - url: https://api.halal.sh/v1 description: Production security: - apiKey: [] tags: - name: Instruments description: Compliance, financials, evidence, history, and health for a single stock. - name: Screening description: Batch screening and search across the instrument universe. - name: ETFs description: Shariah purity and holdings breakdown for ETFs. - name: Methodology description: The screening methodology, its thresholds, and version. paths: /screen: post: tags: - Screening summary: Screen instruments description: > Screen stocks in one request. Provide either: - `symbols` — up to 50 specific stock tickers (available on every plan), or - filters (`status`, `sector`, `market_cap`, `health`) to discover matching stocks across the universe (requires the Plus plan). This endpoint screens **equities**. ETF tickers don't resolve here — they are returned in `meta.not_found`; use `GET /etfs/{symbol}` for funds. Returns `200` with an empty array when nothing matches. operationId: screenInstruments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScreenRequest' responses: '200': description: Screening results content: application/json: schema: $ref: '#/components/schemas/ScreenResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SandboxRestricted' '429': $ref: '#/components/responses/RateLimited' components: schemas: ScreenRequest: type: object properties: symbols: type: array items: type: string maxItems: 50 description: Specific tickers to screen (max 50). Available on every plan. example: - AAPL - MSFT - NVDA - JPM status: description: Filter by compliance status (Plus plan). String or array. oneOf: - $ref: '#/components/schemas/ComplianceStatus' - type: array items: $ref: '#/components/schemas/ComplianceStatus' sector: type: string description: Filter by sector, e.g. "Technology" (Plus plan). market_cap: description: Filter by market-cap band (Plus plan). String or array. oneOf: - type: string enum: - small - mid - large - mega - type: array items: type: string enum: - small - mid - large - mega health: description: Filter by financial health (Plus plan). String or array. oneOf: - $ref: '#/components/schemas/HealthStatus' - type: array items: $ref: '#/components/schemas/HealthStatus' limit: type: integer default: 50 maximum: 100 offset: type: integer default: 0 ScreenResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ScreenResult' meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: type: integer description: Number of results returned. requested: type: integer description: Symbols requested (symbol mode). not_found: type: array items: type: string description: >- Requested symbols that don't resolve to a known stock — unknown tickers, or ETF tickers (use /etfs) (symbol mode). sandbox_restricted: type: array items: type: string description: >- Requested symbols dropped because they fall outside the sandbox universe. Present only for sandbox keys that requested out-of-universe symbols; omitted otherwise (symbol mode). limit: type: integer description: Page size (filter mode). offset: type: integer description: Current offset (filter mode). ComplianceStatus: type: string enum: - compliant - non-compliant - pending description: | Compliance determination. `pending` means the instrument has not been analysed yet. This enum may gain values in future; treat any unknown value as `pending`. HealthStatus: type: string enum: - fragile - robust - antifragile nullable: true description: Financial resilience rating, independent of Shariah compliance. ScreenResult: type: object properties: symbol: type: string example: AAPL name: type: string example: Apple Inc. compliance_status: $ref: '#/components/schemas/ComplianceStatus' health_status: $ref: '#/components/schemas/HealthStatus' market_data: type: object properties: price: type: number nullable: true change_24h: type: number nullable: true change_percent_24h: type: number nullable: true Meta: type: object properties: request_id: type: string description: Unique ID for this request. Include it in support requests. example: req_abc123 as_of: type: string format: date-time description: When this response was generated. methodology: type: string description: Methodology used, as `id@version`. Present on compliance responses. example: aaoifi-ss21@2026.1 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - bad_request - unauthorized - sandbox_restricted - not_found - rate_limit_exceeded - service_unavailable - internal_error example: not_found message: type: string example: No instrument found for symbol 'XYZ'. retry_after: type: integer description: Seconds until the rate limit resets (only on 429). meta: $ref: '#/components/schemas/Meta' responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: bad_request message: Maximum 50 symbols per request. meta: request_id: req_abc123 Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or revoked API key. meta: request_id: req_abc123 SandboxRestricted: description: Symbol or feature not available on the sandbox plan content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: sandbox_restricted message: >- Symbol 'TSLA' is not available in the sandbox. Upgrade to Plus for full access. meta: request_id: req_abc123 RateLimited: description: Rate limit exceeded headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed in the current daily window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current daily window. X-RateLimit-Reset: schema: type: string format: date-time description: ISO 8601 timestamp when the daily window resets (midnight UTC). Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Daily request limit (100) exceeded. Resets at midnight UTC. retry_after: 3600 meta: request_id: req_abc123 securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````