ValueRay Symbol Data API

openapi: 3.0.3
info:
  title: ValueRay Symbol Data API
  description: >-
    AI-ready financial data API returning a comprehensive snapshot of
    technical, quantitative, sentiment, risk, and performance data for a
    single stock or ETF symbol. Responses are designed for AI agents and
    LLMs that need explainable financial overviews of specific symbols.
  version: '1.0'
  contact:
    name: ValueRay
    url: https://www.valueray.com/
  termsOfService: https://www.valueray.com/
servers:
  - url: https://www.valueray.com/api/v1
    description: ValueRay API v1 production endpoint
tags:
  - name: Symbol Data
    description: Aggregated technical, quantitative, and sentiment data for a single symbol.
paths:
  /symbolData:
    get:
      summary: Get Symbol Data
      description: >-
        Returns an AI-ready aggregate of technical, quantitative, and
        sentiment data for the supplied stock or ETF symbol, including
        market identifiers, market cap, dividend information, technical
        indicators, risk metrics, support and resistance levels, zigzag
        pivot points, change points, performance returns, and sentiment
        scoring.
      operationId: getSymbolData
      tags:
        - Symbol Data
      parameters:
        - name: symbol
          in: query
          required: true
          description: Ticker symbol of the stock or ETF (e.g., AAPL, SPY, VTI).
          schema:
            type: string
            example: AAPL
      responses:
        '200':
          description: Aggregated symbol data response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SymbolDataResponse'
              examples:
                aapl:
                  summary: Apple Inc (AAPL) common stock
                  value:
                    'common stock: AAPL (Apple Inc) on NASDAQ':
                      last_update: '2026-05-06 18:09:33'
                      code: AAPL
                      exchange: NASDAQ
                      isin: US0378331005
                      type: common stock
                      name: Apple Inc
                      currency: USD
                      country: USA
                      country_origin: United States
                      market_cap_in_millions: '3983727.39'
                      sector: Technology
                      industry: Consumer Electronics
                      peer_group: Technology Hardware, Storage & Peripherals
                      keywords: Smartphones, Computers, Tablets, Wearables, Digital Services
                    disclaimer: All data is for informational purposes and does not constitute financial advice. Always combine it with your own research.
                    field_explanations: https://www.valueray.com/prompts/_explanations.md
        '400':
          description: Bad request (e.g., missing or invalid symbol parameter).
        '403':
          description: Forbidden (e.g., authentication or rate limit gating).
        '429':
          description: Too many requests (rate limit exceeded).
components:
  schemas:
    SymbolDataResponse:
      type: object
      description: >-
        Top-level wrapper. Contains a single descriptive key whose value is
        a SymbolData object, plus disclaimer and field_explanations
        pointers. The descriptive key follows the pattern
        "{type}: {code} ({name}) on {exchange}".
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/SymbolData'
          - type: string
      required:
        - disclaimer
        - field_explanations
      properties:
        disclaimer:
          type: string
          description: Standard informational disclaimer.
        field_explanations:
          type: string
          format: uri
          description: URL to the canonical field definitions and scoring logic document.
    SymbolData:
      type: object
      description: Aggregated symbol data covering identity, market, technical, risk, sentiment, and performance dimensions.
      properties:
        last_update:
          type: string
          description: Timestamp of the last data refresh.
          example: '2026-05-06 18:09:33'
        code:
          type: string
          description: Ticker code.
          example: AAPL
        exchange:
          type: string
          description: Listing exchange.
          example: NASDAQ
        isin:
          type: string
          description: International Securities Identification Number.
          example: US0378331005
        type:
          type: string
          description: Instrument type (e.g., "common stock", "etf").
          example: common stock
        name:
          type: string
          description: Issuer or fund display name.
          example: Apple Inc
        currency:
          type: string
          description: Listing currency code.
          example: USD
        country:
          type: string
          description: Listing country code.
          example: USA
        country_origin:
          type: string
          description: Country of origin or domicile (display name).
          example: United States
        market_cap_in_millions:
          type: string
          description: Market capitalization in millions of the listing currency.
          example: '3983727.39'
        sector:
          type: string
          description: GICS-style sector classification.
          example: Technology
        industry:
          type: string
          description: GICS-style industry classification.
          example: Consumer Electronics
        peer_group:
          type: string
          description: Sub-industry or peer group label used for percentile comparisons.
          example: Technology Hardware, Storage & Peripherals
        etf_category:
          type: string
          description: Category label for ETFs (e.g., "Large Blend"). Stocks omit this field.
          example: Large Blend
        keywords:
          type: string
          description: Comma-separated descriptive keywords for the issuer or fund.
        dividends:
          $ref: '#/components/schemas/Dividends'
        technical:
          $ref: '#/components/schemas/Technical'
        risk:
          $ref: '#/components/schemas/Risk'
        support_resistance:
          type: array
          description: Identified support and resistance levels with strength ratings.
          items:
            $ref: '#/components/schemas/SupportResistanceLevel'
        zigzag_pivot_points:
          type: array
          description: Pivot points generated by a zigzag algorithm tracking price reversals.
          items:
            $ref: '#/components/schemas/ZigzagPivot'
        changepoints:
          type: array
          description: Detected regime change points in the price or volume series.
          items:
            $ref: '#/components/schemas/Changepoint'
        performance:
          $ref: '#/components/schemas/Performance'
        sentiment:
          $ref: '#/components/schemas/Sentiment'
    Dividends:
      type: object
      description: Dividend rate, yield, growth, and payout details.
      properties:
        rate:
          type: number
          description: Most recent annual dividend rate.
        yield:
          type: number
          description: Annual dividend yield as a percentage.
        payout_ratio:
          type: number
          description: Payout ratio as a percentage of earnings.
        growth_5y:
          type: number
          description: 5-year dividend growth rate.
        streak_years:
          type: integer
          description: Number of consecutive years of dividend growth or payment.
        next_payment:
          type: string
          description: Status or scheduled date of the next dividend payment.
    Technical:
      type: object
      description: Technical indicators and price/volume metrics.
      properties:
        last_price:
          type: number
        '52w_high':
          type: number
        '52w_low':
          type: number
        ema_20:
          type: number
        sma_50:
          type: number
        sma_200:
          type: number
        atr:
          type: number
          description: Average True Range.
        volatility:
          type: number
          description: Volatility percentage.
        current_volume:
          type: number
        average_volume_20d:
          type: number
        hurst_exponent:
          type: number
          description: Hurst exponent for trend persistence (commonly returned for ETFs).
        trend_correlation:
          type: number
          description: Trend correlation against a reference (commonly returned for ETFs).
    Risk:
      type: object
      description: Risk-adjusted performance and tail-risk metrics.
      properties:
        safety_score:
          type: number
          description: Composite safety score (0-100).
          example: 86.7
        beta:
          type: number
        alpha:
          type: number
        sharpe_ratio:
          type: number
        max_drawdown:
          type: number
        value_at_risk:
          type: number
          description: Value at Risk metric.
        tail_risk:
          type: number
          description: Tail risk assessment.
    SupportResistanceLevel:
      type: object
      description: A support or resistance price level with strength rating and date range.
      properties:
        level:
          type: number
        type:
          type: string
          enum: [support, resistance]
        strength:
          type: string
          description: Strength rating (e.g., weak, moderate, strong).
        from:
          type: string
        to:
          type: string
    ZigzagPivot:
      type: object
      description: A zigzag pivot point indicating a price reversal.
      properties:
        date:
          type: string
        price:
          type: number
        direction:
          type: string
          enum: [up, down]
    Changepoint:
      type: object
      description: A detected regime change point in the price or volume series.
      properties:
        date:
          type: string
        metric:
          type: string
        value:
          type: number
    Performance:
      type: object
      description: Trailing return metrics across multiple horizons.
      properties:
        '1d':
          type: number
        '1w':
          type: number
        '1m':
          type: number
        '3m':
          type: number
        '6m':
          type: number
        ytd:
          type: number
        '1y':
          type: number
        '3y':
          type: number
        '5y':
          type: number
        cagr:
          type: number
          description: Compound annual growth rate.
        relative_strength:
          type: number
          description: Relative strength score versus the broader market.
    Sentiment:
      type: object
      description: Sentiment indicators including RSI, VRO score, and rotation signals.
      properties:
        rsi:
          type: number
          description: Relative Strength Index.
        vro_score:
          type: number
          description: ValueRay's proprietary VRO score.
        buy_signal:
          type: string
          description: Aggregate buy/sell/neutral indicator.
        sector_rotation:
          type: string
          description: Sector rotation classification.
        industry_rotation:
          type: string
          description: Industry rotation classification.
        market_regime:
          type: string
          description: Detected market regime label.