Equity Rank Screener API

openapi: 3.2.0
info:
  title: Equity Rank Com Screener API
  version: 0.1.0
  description: 'Operations tagged screener 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: Screener
paths:
  /api/screener:
    get:
      tags:
      - Screener
      summary: Get Screener
      description: 'Stock screener.

        - Unauthenticated: returns limited fields (ticker, company_name, sector, score, mos_pct) for top 50 stocks.

        - Authenticated with active subscription: returns full screener response (existing behavior).


        Full response logic:

        1. Fetch all scored rows from screener_cache (save_score not null).

        2. Compute the 90th-percentile score threshold — exposed as `count`

        so the UI can show pool size for context.

        3. Return the top 20 stocks by overall_score (falls back to save_score)

        from the top-decile pool. Admin-curated weekly picks override when

        present.'
      operationId: get_screener_api_screener_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/screener/iv-percentile:
    get:
      tags:
      - Screener
      summary: Get Iv Percentile Screener
      description: 'Free IV Percentile Screener — no auth required.

        Returns the most-recent iv_daily_snapshot rows joined with screener_cache,

        sorted by iv_rank DESC. Results cached 1 hour in memory.'
      operationId: get_iv_percentile_screener_api_screener_iv_percentile_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/screener/browse:
    get:
      tags:
      - Screener
      summary: Browse Screener
      description: 'Browse the full screener_cache with optional filtering.

        Returns stocks matching filters, sorted by sort_by descending.

        Used by the dashboard inline screener panel.

        Filtering and limiting are pushed to Supabase to avoid full-table transfers.'
      operationId: browse_screener_api_screener_browse_get
      security:
      - HTTPBearer: []
      parameters:
      - name: sector
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by sector (partial match)
          title: Sector
        description: Filter by sector (partial match)
      - name: min_score
        in: query
        required: false
        schema:
          type: number
          description: Minimum Fundamentals Score (0-100)
          default: 0.0
          title: Min Score
        description: Minimum Fundamentals Score (0-100)
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          description: Column to sort by
          default: equity_rank_score
          title: Sort By
        description: Column to sort by
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 100
          title: Limit
      - name: full_data_only
        in: query
        required: false
        schema:
          type: boolean
          description: When true, exclude rows where has_full_data is false
          default: true
          title: Full Data Only
        description: When true, exclude rows where has_full_data is false
      - name: min_piotroski_score
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 9
            minimum: 0
          - type: 'null'
          description: Minimum Piotroski F-Score (0–9)
          title: Min Piotroski Score
        description: Minimum Piotroski F-Score (0–9)
      - name: graham_below_price
        in: query
        required: false
        schema:
          type: boolean
          description: When true, only show stocks trading below their Graham Number
          default: false
          title: Graham Below Price
        description: When true, only show stocks trading below their Graham Number
      - name: min_sue_score
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 10.0
            minimum: -10.0
          - type: 'null'
          description: Minimum SUE z-score (BST-01); winsorized to [-10, 10]
          title: Min Sue Score
        description: Minimum SUE z-score (BST-01); winsorized to [-10, 10]
      - name: min_eps_revision_ratio
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          description: Minimum EPS revision ratio — upward share of past-30-day analyst revisions [0.0, 1.0] (BST-02)
          title: Min Eps Revision Ratio
        description: Minimum EPS revision ratio — upward share of past-30-day analyst revisions [0.0, 1.0] (BST-02)
      - name: max_short_ratio
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          description: Maximum days-to-cover short ratio (factual ceiling filter)
          title: Max Short Ratio
        description: Maximum days-to-cover short ratio (factual ceiling filter)
      - name: max_illiquidity_premium
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 0.05
            minimum: 0.0
          - type: 'null'
          description: Maximum Amihud illiquidity premium (0.0–0.05). Set to 0.01 to filter for liquid names only. Rows without illiquidity data are excluded when this filter is active.
          title: Max Illiquidity Premium
        description: Maximum Amihud illiquidity premium (0.0–0.05). Set to 0.01 to filter for liquid names only. Rows without illiquidity data are excluded when this filter is active.
      - name: min_roic
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 2.0
            minimum: -1.0
          - type: 'null'
          description: Minimum ROIC, decimal fraction (0.15 = 15%). Rows without ROIC data are excluded when active.
          title: Min Roic
        description: Minimum ROIC, decimal fraction (0.15 = 15%). Rows without ROIC data are excluded when active.
      - name: min_gross_margin
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: -100.0
          - type: 'null'
          description: Minimum gross margin, PERCENT scale (35.0 = 35%). Rows without gross margin data are excluded when active.
          title: Min Gross Margin
        description: Minimum gross margin, PERCENT scale (35.0 = 35%). Rows without gross margin data are excluded when active.
      - name: min_net_margin
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 150.0
            minimum: -300.0
          - type: 'null'
          description: Minimum net margin, PERCENT scale (8.0 = 8%). Rows without net margin data are excluded when active.
          title: Min Net Margin
        description: Minimum net margin, PERCENT scale (8.0 = 8%). Rows without net margin data are excluded when active.
      - name: min_revenue_growth
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 1000.0
            minimum: -100.0
          - type: 'null'
          description: Minimum revenue growth YoY, PERCENT scale (8.0 = 8%). Rows without revenue growth data are excluded when active.
          title: Min Revenue Growth
        description: Minimum revenue growth YoY, PERCENT scale (8.0 = 8%). Rows without revenue growth data are excluded when active.
      - name: min_eps_growth
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 1000.0
            minimum: -100.0
          - type: 'null'
          description: Minimum EPS growth YoY, PERCENT scale (12.0 = 12%). Rows without EPS growth data are excluded when active.
          title: Min Eps Growth
        description: Minimum EPS growth YoY, PERCENT scale (12.0 = 12%). Rows without EPS growth data are excluded when active.
      - name: min_fcf_yield
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: -1.0
          - type: 'null'
          description: Minimum FCF yield, decimal fraction (0.05 = 5%). Rows without FCF yield data are excluded when active.
          title: Min Fcf Yield
        description: Minimum FCF yield, decimal fraction (0.05 = 5%). Rows without FCF yield data are excluded when active.
      - name: max_net_debt_to_ebitda
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 50.0
            minimum: -10.0
          - type: 'null'
          description: Maximum net debt / EBITDA leverage ratio (e.g. 2.5 = 2.5x). Rows without leverage data are excluded when active.
          title: Max Net Debt To Ebitda
        description: Maximum net debt / EBITDA leverage ratio (e.g. 2.5 = 2.5x). Rows without leverage data are excluded when active.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/screener/demo:
    get:
      tags:
      - Screener
      summary: Screener Demo
      description: 'Public no-auth demo screener (LEAD-01). Runs one of 3 server-defined presets

        against the in-memory cache via the SHARED _filter_and_sort_rows helper (LEAD-04),

        capped at 10 rows server-side (LEAD-02), returning only non-gated public fields.'
      operationId: screener_demo_api_screener_demo_get
      parameters:
      - name: preset
        in: query
        required: true
        schema:
          type: string
          description: Preset slug
          title: Preset
        description: Preset slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/screener/sector/{sector}:
    get:
      tags:
      - Screener
      summary: Screener Sector
      description: 'Public no-auth sector index (SEO-04). Reuses the shared filter helper and

        the public-safe row allowlist — the same data path as the demo, scoped to one

        sector. A GICS parent name expands to its exact platform-label family via

        _GICS_SECTOR_FAMILY (see above); any other value falls through to

        _filter_and_sort_rows'' sanitized partial match, so an unknown sector returns

        an empty list rather than an error and no extra validation is needed.'
      operationId: screener_sector_api_screener_sector__sector__get
      parameters:
      - name: sector
        in: path
        required: true
        schema:
          type: string
          title: Sector
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/screener/dividend-growth/{sector}/{band}:
    get:
      tags:
      - Screener
      summary: Screener Dividend Growth
      description: 'Public no-auth dividend-growth sector×band screener (GROW-02).


        Returns up to 20 filtered rows for the given sector slug and yield band slug.

        Results are cached 4 hours in memory (33 slots). Uses _demo_public_row allowlist.'
      operationId: screener_dividend_growth_api_screener_dividend_growth__sector___band__get
      parameters:
      - name: sector
        in: path
        required: true
        schema:
          type: string
          title: Sector
      - name: band
        in: path
        required: true
        schema:
          type: string
          title: Band
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/screener/ask:
    post:
      tags:
      - Screener
      summary: Screener Ask
      description: 'Conversational screener. NL query -> filters -> existing screen. Always 200.


        ASK-03 advice-free guarantee is STRUCTURAL: the LLM''s only output channel is the

        emit_filters tool schema, so it cannot emit a buy/sell sentence. The only

        user-facing strings the backend authors are the fixed CLARIFY_* constants.'
      operationId: screener_ask_api_screener_ask_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    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
    AskRequest:
      properties:
        query:
          type: string
          title: Query
      type: object
      required:
      - query
      title: AskRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BrowseResponse:
      properties:
        stocks:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Stocks
        count:
          type: integer
          title: Count
        universe_size:
          type: integer
          title: Universe Size
        show_activation_invite:
          type: boolean
          title: Show Activation Invite
          default: false
      type: object
      required:
      - stocks
      - count
      - universe_size
      title: BrowseResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- equity-rank-com-openapi.yml