Equity Rank Valuation Split API

openapi: 3.2.0
info:
  title: Equity Rank Com Valuation Split API
  version: 0.1.0
  description: 'Operations tagged valuation-split across 2 of this provider''s published API definitions: openapi.json, equity-rank-com-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: valuation-split
paths:
  /api/valuation/{symbol}/snapshot:
    get:
      tags:
      - valuation-split
      summary: Get Valuation Snapshot
      description: 'Return the TTM point-in-time valuation snapshot for a stock.


        Cache-first: reads from the in-memory valuation cache populated by

        GET /api/stocks/{symbol}/valuation. Returns 503 if cache is cold.'
      operationId: get_valuation_snapshot_api_valuation__symbol__snapshot_get
      security:
      - HTTPBearer: []
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValuationSnapshot'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/valuation/{symbol}/projection:
    get:
      tags:
      - valuation-split
      summary: Get Valuation Projection
      description: 'Return 1-year bear/base/bull model scenarios for a stock.


        Fetches live stock data and runs compute_projected_fair_value_range at a

        1-year model horizon. Returns a partial envelope (data_complete=false) when

        financial inputs are insufficient — never returns 500 on data gaps.


        Model scenarios only. Not a model fair value range under model scenarios or

        investment advice. For informational and educational purposes only.'
      operationId: get_valuation_projection_api_valuation__symbol__projection_get
      security:
      - HTTPBearer: []
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectionEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/valuation/{symbol}:
    get:
      tags:
      - valuation-split
      summary: Get Valuation Envelope
      description: 'Return the combined ValuationEnvelope (snapshot + optional projection).


        schema_version="2.0" signals to clients that this is the split-format response.

        Projection is best-effort: if compute fails, snapshot is still returned with

        projection=null. Returns 503 if the snapshot cache is cold.'
      operationId: get_valuation_envelope_api_valuation__symbol__get
      security:
      - HTTPBearer: []
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValuationEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValuationSnapshot:
      properties:
        symbol:
          type: string
          title: Symbol
        price:
          anyOf:
          - type: number
          - type: 'null'
          title: Price
        sector:
          anyOf:
          - type: string
          - type: 'null'
          title: Sector
        company_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Type
        consensus_fair_value:
          anyOf:
          - type: number
          - type: 'null'
          title: Consensus Fair Value
        consensus_margin_of_safety:
          anyOf:
          - type: number
          - type: 'null'
          title: Consensus Margin Of Safety
        methods_used:
          items:
            type: string
          type: array
          title: Methods Used
        best_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Best Method
        best_fit:
          anyOf:
          - $ref: '#/components/schemas/BestFit'
          - type: 'null'
        model_confidence_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Model Confidence Score
        model_confidence_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Confidence Label
        fair_value_low:
          anyOf:
          - type: number
          - type: 'null'
          title: Fair Value Low
        fair_value_high:
          anyOf:
          - type: number
          - type: 'null'
          title: Fair Value High
        combined_adjusted_fair_value:
          anyOf:
          - type: number
          - type: 'null'
          title: Combined Adjusted Fair Value
        combined_adjusted_margin_of_safety:
          anyOf:
          - type: number
          - type: 'null'
          title: Combined Adjusted Margin Of Safety
        fair_value_interval:
          anyOf:
          - $ref: '#/components/schemas/FairValueInterval'
          - type: 'null'
        data_quality:
          anyOf:
          - type: string
          - type: 'null'
          title: Data Quality
          default: full
        data_as_of:
          anyOf:
          - type: string
          - type: 'null'
          title: Data As Of
        last_updated:
          type: string
          title: Last Updated
      type: object
      required:
      - symbol
      title: ValuationSnapshot
      description: 'Point-in-time valuation — TTM/most-recent fundamentals only.


        Derived from ValuationResult via snapshot_from_valuation_result().

        Does NOT include forward-scenario outputs — those belong in ValuationProjection.

        ValuationResult is unchanged; this is a curated view of it for new endpoints.'
    ValuationProjection:
      properties:
        ticker:
          type: string
          title: Ticker
        scenario:
          type: string
          title: Scenario
        horizon_years:
          type: integer
          title: Horizon Years
        projected_fair_value:
          anyOf:
          - type: number
          - type: 'null'
          title: Projected Fair Value
        assumed_growth_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Assumed Growth Rate
        model_fair_value_differential_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Model Fair Value Differential Pct
        assumptions:
          additionalProperties: true
          type: object
          title: Assumptions
        assumptions_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Assumptions Note
        disclaimer:
          type: string
          title: Disclaimer
          default: ''
      type: object
      required:
      - ticker
      - scenario
      - horizon_years
      title: ValuationProjection
      description: 'Single forward scenario (bear / base / bull) for a given model horizon.


        Produced by projection_service.compute_projected_fair_value_range() and

        converted via projection_from_scenario(). One row per scenario.


        Not a projected fair value range under model scenarios or investment advice.

        For informational and educational purposes only.'
    ValuationEnvelope:
      properties:
        snapshot:
          $ref: '#/components/schemas/ValuationSnapshot'
        projection:
          anyOf:
          - $ref: '#/components/schemas/ProjectionEnvelope'
          - type: 'null'
        schema_version:
          type: string
          title: Schema Version
          default: '2.0'
      type: object
      required:
      - snapshot
      title: ValuationEnvelope
      description: 'Combined snapshot + projection response for GET /api/valuation/{symbol}.

        schema_version field lets clients detect the new split format.'
    ProjectionEnvelope:
      properties:
        bear:
          anyOf:
          - $ref: '#/components/schemas/ValuationProjection'
          - type: 'null'
        base:
          anyOf:
          - $ref: '#/components/schemas/ValuationProjection'
          - type: 'null'
        bull:
          anyOf:
          - $ref: '#/components/schemas/ValuationProjection'
          - type: 'null'
        data_complete:
          type: boolean
          title: Data Complete
          default: false
        horizon_years:
          type: integer
          title: Horizon Years
          default: 1
        range_low:
          anyOf:
          - type: number
          - type: 'null'
          title: Range Low
        range_high:
          anyOf:
          - type: number
          - type: 'null'
          title: Range High
        disclaimer:
          type: string
          title: Disclaimer
          default: ''
      type: object
      title: ProjectionEnvelope
      description: All three bear/base/bull scenarios for a given ticker + horizon.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FairValueInterval:
      properties:
        low:
          type: number
          title: Low
        high:
          type: number
          title: High
        confidence:
          type: number
          title: Confidence
          default: 0.8
      type: object
      required:
      - low
      - high
      title: FairValueInterval
      description: 'Phase 47 / CI-01..04: 80% confidence band on a fair value point estimate.


        The band combines two uncertainty sources:

        - Cross-method disagreement (IQR-based, robust to DCF tail outliers)

        - Sector-vol within-method spread (decile-bucketed multiplier × FV)


        `confidence` is always 0.80 in v2.0; reserved for v2.1+ scenario weights.

        Copy framing in UI must use "80% model interval" — NEVER "forecast",

        "expected range", or "price target" (banned per CLAUDE.md).'
    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
    BestFit:
      properties:
        method:
          type: string
          title: Method
        label:
          type: string
          title: Label
        fair_value:
          type: number
          title: Fair Value
        margin_of_safety:
          type: number
          title: Margin Of Safety
        rationale:
          type: string
          title: Rationale
        confidence:
          type: string
          title: Confidence
        method_no_leverage:
          anyOf:
          - type: string
          - type: 'null'
          title: Method No Leverage
        label_no_leverage:
          anyOf:
          - type: string
          - type: 'null'
          title: Label No Leverage
        fair_value_no_leverage:
          anyOf:
          - type: number
          - type: 'null'
          title: Fair Value No Leverage
        margin_of_safety_no_leverage:
          anyOf:
          - type: number
          - type: 'null'
          title: Margin Of Safety No Leverage
        confidence_no_leverage:
          anyOf:
          - type: string
          - type: 'null'
          title: Confidence No Leverage
        leverage_fired:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Leverage Fired
        leverage_debt_equity:
          anyOf:
          - type: number
          - type: 'null'
          title: Leverage Debt Equity
        bridge_observed:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Bridge Observed
        rule_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Rule Sha
      type: object
      required:
      - method
      - label
      - fair_value
      - margin_of_safety
      - rationale
      - confidence
      title: BestFit
      description: The single best-fitting valuation method for this specific stock.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- equity-rank-com-openapi.yml