> ## 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.

# Get Instrument

> Returns identity, current market data, a compliance summary, and a
health summary for a stock. Use the dedicated endpoints below for the
full compliance determination, extracted financials, or health ratios.




## OpenAPI

````yaml GET /instruments/{symbol}
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:
  /instruments/{symbol}:
    get:
      tags:
        - Instruments
      summary: Get an instrument
      description: |
        Returns identity, current market data, a compliance summary, and a
        health summary for a stock. Use the dedicated endpoints below for the
        full compliance determination, extracted financials, or health ratios.
      operationId: getInstrument
      parameters:
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Instrument found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/SandboxRestricted'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Symbol:
      name: symbol
      in: path
      required: true
      description: Stock ticker symbol (e.g. AAPL, NVDA, MSFT).
      schema:
        type: string
        minLength: 1
        maxLength: 10
        example: AAPL
  schemas:
    InstrumentResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Instrument'
        meta:
          $ref: '#/components/schemas/Meta'
    Instrument:
      type: object
      properties:
        symbol:
          type: string
          example: AAPL
        name:
          type: string
          example: Apple Inc.
        country_code:
          type: string
          nullable: true
          example: US
          description: ISO 3166-1 alpha-2 country of primary listing.
        exchange:
          type: string
          nullable: true
          example: Nasdaq
        sector:
          type: string
          nullable: true
          example: Technology
        industry:
          type: string
          nullable: true
          example: Consumer Electronics
        stock_status:
          type: string
          enum:
            - active
            - inactive
            - delisted
        delisted_at:
          type: string
          format: date-time
          nullable: true
        market_data:
          $ref: '#/components/schemas/MarketData'
        compliance:
          type: object
          properties:
            status:
              $ref: '#/components/schemas/ComplianceStatus'
            confidence:
              type: number
              nullable: true
              example: 0.95
            has_analysis:
              type: boolean
            methodology:
              type: string
              example: aaoifi-ss21@2026.1
        health:
          type: object
          properties:
            status:
              $ref: '#/components/schemas/HealthStatus'
            has_analysis:
              type: boolean
        ethical_screening:
          $ref: '#/components/schemas/EthicalScreening'
    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'
    MarketData:
      type: object
      properties:
        price:
          type: number
          nullable: true
          example: 315.05
        currency:
          type: string
          example: USD
        change_24h:
          type: number
          nullable: true
          example: 8.09
        change_percent_24h:
          type: number
          nullable: true
          example: 2.6355
        market_cap:
          type: number
          nullable: true
          example: 4109006116320
        as_of:
          type: string
          format: date-time
          nullable: true
    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.
    EthicalScreening:
      type: object
      description: >
        Ethical-screening summary, independent of AAOIFI financial compliance.

        Flags involvement in areas such as occupation or weapons, aggregated
        from

        independent research sources.
      properties:
        status:
          type: string
          enum:
            - flagged
            - cleared
            - not_screened
        severity:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
          nullable: true
          description: >-
            Worst severity across flagged areas; null when cleared or not
            screened.
        flagged_areas:
          type: array
          items:
            type: string
          example:
            - occupation
        area_severities:
          type: object
          additionalProperties:
            type: string
          example:
            occupation: low
        source_count:
          type: integer
          example: 1
        last_verified:
          type: string
          format: date-time
          nullable: true
  responses:
    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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: No instrument found for symbol 'XYZ'.
            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

````