perspicium-api-v0.yaml

openapi: 3.1.0
info:
  title: Perspicium Public API
  version: "0"
  description: Key-protected public API for Perspicium market analytics.
servers:
  - url: https://perspicium.com/api/v0
security:
  - ApiKeyAuth: []
paths:
  /ping:
    get:
      summary: Health check
      responses:
        "200":
          description: API is reachable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
  /options/expected-move:
    get:
      summary: Expected move bands
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - $ref: "#/components/parameters/RangePctDefaultOne"
      responses:
        "200":
          description: Expected move data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /options/iv:
    get:
      summary: Implied volatility smile and term structure
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - $ref: "#/components/parameters/RangePctDefaultPoint15"
      responses:
        "200":
          description: Implied volatility data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /options/open-interest:
    get:
      summary: Open interest, volume, or premium summary
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - name: range_pct
          in: query
          schema:
            type: number
            default: 0.25
            minimum: 0.01
            maximum: 2
        - $ref: "#/components/parameters/Basis"
        - $ref: "#/components/parameters/Expiration"
      responses:
        "200":
          description: Open interest summaries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /options/uoa:
    get:
      summary: Unusual options activity
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - name: include_0dte
          in: query
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 10
            maximum: 100
      responses:
        "200":
          description: Unusual activity records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /options/chain:
    get:
      summary: Option chain rows
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - $ref: "#/components/parameters/RangePctDefaultPoint15"
        - name: expiry
          in: query
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Option chain records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /greeks/gex:
    get:
      summary: Gamma exposure profile
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - $ref: "#/components/parameters/Basis"
        - $ref: "#/components/parameters/Expiration"
        - $ref: "#/components/parameters/RangePctDefaultOne"
      responses:
        "200":
          description: Gamma exposure profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/risk:
    get:
      summary: Risk and performance metrics
      parameters:
        - name: ticker
          in: query
          schema:
            type: string
            default: NVDA
        - name: benchmark
          in: query
          schema:
            type: string
            default: SPY
        - $ref: "#/components/parameters/Period5y"
        - $ref: "#/components/parameters/Window60"
      responses:
        "200":
          description: Risk metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/asset-correlation:
    get:
      summary: Cross-asset correlation analytics
      parameters:
        - name: period
          in: query
          schema:
            type: string
            default: 3y
        - name: window
          in: query
          schema:
            type: integer
            default: 90
            minimum: 5
            maximum: 365
      responses:
        "200":
          description: Asset correlation analytics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/market-memory:
    get:
      summary: Historical pattern matching
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - name: similarity
          in: query
          schema:
            type: string
            default: cosine
            enum: [cosine, dot, spearman]
        - name: kernel_size
          in: query
          schema:
            type: integer
            default: 30
            minimum: 5
            maximum: 365
        - name: top_n
          in: query
          schema:
            type: integer
            default: 5
            minimum: 1
            maximum: 20
        - name: min_separation
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 365
      responses:
        "200":
          description: Historical analog matches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/portfolio-optimizer:
    get:
      summary: Portfolio optimization
      parameters:
        - name: tickers
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: array
            maxItems: 20
            items:
              type: string
          example: [SPY, QQQ, TLT]
        - name: objective
          in: query
          schema:
            type: string
            default: sharpe
            enum: [sharpe, min_var, equal_weight]
        - $ref: "#/components/parameters/Period5y"
      responses:
        "200":
          description: Optimized portfolio metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/seasonality:
    get:
      summary: Seasonality analytics
      parameters:
        - $ref: "#/components/parameters/TickerSPY"
        - name: grouping
          in: query
          schema:
            type: string
            default: monthly
            enum: [monthly, quarterly, weekday, calendar, presidential]
        - name: period
          in: query
          schema:
            type: string
            default: 10y
      responses:
        "200":
          description: Seasonality analytics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
  /quant/sector-insights:
    get:
      summary: Sector breadth and return analytics
      parameters:
        - name: period
          in: query
          schema:
            type: string
            default: 1M
      responses:
        "200":
          description: Sector analytics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessEnvelope"
        default:
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Use `Authorization: ApiKey YOUR_TOKEN`."
  parameters:
    TickerSPY:
      name: ticker
      in: query
      schema:
        type: string
        default: SPY
      example: SPY
    RangePctDefaultOne:
      name: range_pct
      in: query
      schema:
        type: number
        default: 1
        minimum: 0.01
        maximum: 2
    RangePctDefaultPoint15:
      name: range_pct
      in: query
      schema:
        type: number
        default: 0.15
        minimum: 0.01
        maximum: 2
    Basis:
      name: basis
      in: query
      schema:
        type: string
        default: open_interest
        enum: [open_interest, volume, total_premium]
    Expiration:
      name: expiration
      in: query
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          format: date
    Period5y:
      name: period
      in: query
      schema:
        type: string
        default: 5y
    Window60:
      name: window
      in: query
      schema:
        type: integer
        default: 60
        minimum: 5
        maximum: 365
  schemas:
    SuccessEnvelope:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          additionalProperties: true
    ErrorEnvelope:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: true
  responses:
    Error:
      description: Error envelope.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"