openapi: 3.0.3
info:
  title: Hound Trader Public Accuracy & Research API
  version: '1.0.0'
  description: |
    Public and Ultimate-tier research endpoints for Hound Trader.

    **Copyright:** Proprietary — Copyright (c) 2024–2026 LUKNAI LLC. All rights reserved.

    **Important:** Responses are informational research data only — not investment advice,
    not trade execution instructions, and not a guarantee of future performance.
    Always pair accuracy figures with https://houndtrader.com/accuracy-methodology
    and https://houndtrader.com/disclaimer.

    Authenticated product APIs under `/api/` (other than documented public paths) require
    a session or Ultimate API key and are not intended as open citation sources.
  contact:
    name: LUKNAI LLC / Hound Trader
    url: https://houndtrader.com/contact
  license:
    name: Proprietary — Copyright LUKNAI LLC. All rights reserved.
    url: https://houndtrader.com/terms

servers:
  - url: https://houndtrader.com
    description: Production

tags:
  - name: PublicAccuracy
    description: Crawlable, no-auth accuracy surfaces for citation and verification
  - name: Ultimate
    description: |
      Authenticated Ultimate Research API. Create `ht_live_` keys in Profile → API Access.
      Auth via Bearer or X-API-Key. Credits deducted per call; `X-Credits-Remaining` on success;
      HTTP 402 when out of credits. HMAC not required when a live API key is present.

paths:
  /accuracy.json:
    get:
      tags: [PublicAccuracy]
      summary: Aggregate accuracy snapshot
      description: |
        Primary machine-readable headline metrics. Prefer `directionalAccuracy` (BUY+SELL, 1D).
        `overallAccuracy` includes HOLD and is secondary.
      parameters:
        - name: timeframe
          in: query
          schema:
            type: string
            enum: [1D, 1W, 1M, 3M, 6M, 1Y, ALL]
            default: ALL
      responses:
        '200':
          description: Snapshot payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccuracySnapshot'

  /accuracy-sample.json:
    get:
      tags: [PublicAccuracy]
      summary: Deterministic graded sample ledger
      description: |
        Newest-first graded 1D outcomes (deduped by symbol/day). Sample window stats
        are not identical to the full-population headline.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 5
            maximum: 100
            default: 25
      responses:
        '200':
          description: Ledger payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccuracyLedger'

  /api/public/accuracy:
    get:
      tags: [PublicAccuracy]
      summary: Same snapshot as /accuracy.json (under /api/)
      description: Prefer /accuracy.json for crawlers; /api/ is broadly Disallowed in robots.txt.
      parameters:
        - name: timeframe
          in: query
          schema:
            type: string
            default: ALL
      responses:
        '200':
          description: Snapshot payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccuracySnapshot'

  /accuracy-feed.xml:
    get:
      tags: [PublicAccuracy]
      summary: Atom feed of methodology changelog and snapshot as-of
      responses:
        '200':
          description: Atom XML feed
          content:
            application/atom+xml:
              schema:
                type: string

  /llms.txt:
    get:
      tags: [PublicAccuracy]
      summary: Citation guide for AI systems
      responses:
        '200':
          description: Plain-text guidance
          content:
            text/plain:
              schema:
                type: string

  /api/predictions:
    get:
      tags: [Ultimate]
      summary: Filtered predictions list
      description: |
        Ultimate plan + API key or Ultimate session. Costs 1 basic credit for external/API-key access.
        Same-origin dashboard traffic may skip the credit gate.
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - name: index
          in: query
          schema:
            type: string
            enum: [sp500, russell2k, russell3k, etf, mutual_fund, extra, all]
        - name: limit
          in: query
          schema:
            type: integer
        - name: symbol
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Predictions payload
          headers:
            X-Credits-Remaining:
              schema:
                type: string
        '401':
          description: Missing or invalid auth
        '402':
          description: Insufficient credits
        '403':
          description: Ultimate plan required

  /api/single:
    get:
      tags: [Ultimate]
      summary: Cached single-symbol research
      description: |
        Full research payload. Anonymous access is denied.
        API key path requires Ultimate and costs 1 basic credit.
        Logged-in session (in-app) is allowed without API-key credit charge.
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cached prediction / research row
          headers:
            X-Credits-Remaining:
              schema:
                type: string
        '401':
          description: Authentication required
        '402':
          description: Insufficient credits (API key)
        '404':
          description: No cached result

  /api/analysis/enhanced:
    post:
      tags: [Ultimate]
      summary: Run enhanced analysis
      description: |
        Runs analysis for a symbol. Session users use normal plan/credit rules.
        API keys require Ultimate. Credit cost matches tier (basic=1, enhanced=5, advanced=15).
        Credits deducted only on successful completion.
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [symbol, analysis_tier]
              properties:
                symbol:
                  type: string
                  example: AAPL
                analysis_tier:
                  type: string
                  enum: [basic, enhanced, advanced]
                ai_model:
                  type: string
                  description: Required for enhanced (e.g. labrador)
                deep_analysis:
                  type: boolean
      responses:
        '200':
          description: Analysis result
          headers:
            X-Credits-Remaining:
              schema:
                type: string
        '401':
          description: Authentication required
        '402':
          description: Insufficient credits
        '403':
          description: Plan or daily-limit gate

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Ultimate API key (`ht_live_…`)
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Ultimate API key (`ht_live_…`)

  schemas:
    AccuracySnapshot:
      type: object
      properties:
        success:
          type: boolean
        metrics:
          type: object
          properties:
            directionalAccuracy:
              type: number
              description: Primary public headline (BUY+SELL)
            directionalTotal:
              type: integer
            directionalCorrect:
              type: integer
            overallAccuracy:
              type: number
              description: Secondary; includes HOLD
            primaryMetric:
              type: string
              example: directional
            horizon:
              type: string
              example: 1D
            isPlaceholder:
              type: boolean
        timeframe:
          type: string
        lastUpdated:
          type: string
          format: date-time
        methodologyVersion:
          type: string
        primaryHorizon:
          type: string
        methodologyUrl:
          type: string
          format: uri
        disclaimerUrl:
          type: string
          format: uri

    AccuracyLedger:
      type: object
      properties:
        success:
          type: boolean
        horizon:
          type: string
        methodologyVersion:
          type: string
        asOf:
          type: string
          format: date-time
        note:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              symbol:
                type: string
              signal:
                type: string
              baseAt:
                type: string
                format: date-time
              returnPct:
                type: number
                nullable: true
              correct:
                type: boolean
                nullable: true
              isDirectional:
                type: boolean