openapi: 3.1.0
info:
  title: GammaEdge API
  version: 1.0.0
paths:
  /v1/expiries/{ticker}:
    get:
      summary: Get next expiration dates for a ticker
      operationId: execute_expiries_v1_expiries__ticker__get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Expiration dates returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpiriesResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/volu/{ticker}:
    get:
      summary: Run volume analytics API
      operationId: execute_volume_v1_volu__ticker__get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      - name: min_dte
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Minimum days to expiration (defaults to full available range)
          title: Min Dte
        description: Minimum days to expiration (defaults to full available range)
      - name: max_dte
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum days to expiration (defaults to full available range)
          title: Max Dte
        description: Maximum days to expiration (defaults to full available range)
      responses:
        '200':
          description: Volume data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vold/{ticker}/slice/{timestamp}:
    get:
      summary: Run volume delta analytics API — single intraday time slice
      operationId: execute_vold_slice_v1_vold__ticker__slice__timestamp__get
      parameters:
      - name: timestamp
        in: path
        required: true
        schema:
          type: string
          description: Intraday time slice in HH:MM format (09:30–16:00 ET)
          title: Timestamp
        description: Intraday time slice in HH:MM format (09:30–16:00 ET)
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Volume delta data returned (single slice)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoldResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vold/{ticker}/latest:
    get:
      summary: Run volume delta analytics API — most recent 5-minute slice only
      operationId: execute_vold_latest_v1_vold__ticker__latest_get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Volume delta data returned (latest slice)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoldResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vold/{ticker}:
    get:
      summary: Run volume delta analytics API
      operationId: execute_vold_v1_vold__ticker__get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Volume delta data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoldResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/centab/{ticker}:
    get:
      summary: Run centroid analytics API
      operationId: execute_centab_v1_centab__ticker__get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Centroid analytics data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CentabResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/specpa/{ticker}:
    get:
      summary: Run specpa analytics API
      operationId: execute_specpa_v1_specpa__ticker__get
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 32
          description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
          title: Ticker
        description: Stock/options ticker symbol (e.g. SPY, QQQ, BRK.B)
      responses:
        '200':
          description: Specpa analytics data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecpaResponse'
        '400':
          description: That ticker symbol doesn't look valid. Please check it and
            try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: This data isn't included in your current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: We don't have data for that ticker. Double-check the symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: We couldn't prepare this data right now. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on our end. Try again, or contact support
            if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: We can't reach the market data right now. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is briefly unavailable. Please try again in a moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: This request took too long. Please try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/usage:
    get:
      tags:
      - usage
      summary: Per-API-key usage for the calling tenant and tier
      operationId: get_tenant_usage_report_v1_usage_get
      parameters:
      - name: start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Window start (YYYY-MM-DD). Defaults to 7 days ago.
          title: Start
        description: Window start (YYYY-MM-DD). Defaults to 7 days ago.
      - name: end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Window end (YYYY-MM-DD). Defaults to today.
          title: End
        description: Window end (YYYY-MM-DD). Defaults to today.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AggregateHealthResult:
      properties:
        status:
          type: string
          title: Status
          description: '"healthy" if every check is healthy, otherwise "degraded".'
        checked_at:
          type: string
          title: Checked At
          description: ISO-8601 UTC timestamp of when the aggregate was assembled.
        checks:
          additionalProperties:
            $ref: '#/components/schemas/HealthCheckResult'
          type: object
          title: Checks
          description: One HealthCheckResult per probed dependency / synthetic command,
            keyed by service name.
      type: object
      required:
      - status
      - checked_at
      - checks
      title: AggregateHealthResult
      description: Response of ``/v1/health/all``.
    CentabResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        session_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Date
          description: ET session calendar date (YYYY-MM-DD)
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ET ISO 8601 timestamp when this response was generated
        expiry_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Date
          description: 0DTE expiry date (YYYY-MM-DD) tracked in this session
        spot_last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Spot Last Updated
          description: ET ISO 8601 timestamp of the most recent snapshot in the data
        slice_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slice Count
          description: Total number of intraday centroid slices
        call_linfit_base_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Call Linfit Base Price
          description: Call centroid strike at session open (session constant)
        put_linfit_base_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Put Linfit Base Price
          description: Put centroid strike at session open (session constant)
        slices:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Slices
          description: Per-snapshot centroid slices ordered by snapshot_timestamp
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - status
      title: CentabResponse
      description: 'Centab API payload.


        Top-level fields expose session-level centroid constants and linfit base prices.

        Each slice in ``slices`` carries per-snapshot centroid strikes/volumes, OLS
        slope

        and rate-of-change metrics, and the linfit EOD projection for calls and puts.'
    CircuitBreakerStatusResponse:
      properties:
        service_name:
          type: string
          title: Service Name
        state:
          type: string
          title: State
        failure_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Failure Count
        last_failure_time:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Failure Time
        last_success_time:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Success Time
      type: object
      required:
      - service_name
      - state
      title: CircuitBreakerStatusResponse
    CommandResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        command_name:
          type: string
          title: Command Name
        result_data:
          anyOf:
          - {}
          - type: 'null'
          title: Result Data
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        execution_time_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Execution Time Seconds
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - status
      - command_name
      title: CommandResponse
    CreateTenantKeyRequest:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Unique tenant identifier (e.g., 'acme-corp').
        tenant_name:
          type: string
          title: Tenant Name
          description: Tenant display name (e.g., 'ACME Corp').
        tier:
          type: string
          title: Tier
          description: Usage-plan tier for the key.
          default: perpetual_internal
        endpoint_prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint Prefix
          description: Optional endpoint prefix to grant this tier (creates an ACL
            rule).
        key_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Value
          description: Pre-existing key value (for migration). If omitted, a secure
            key is generated.
      type: object
      required:
      - tenant_id
      - tenant_name
      title: CreateTenantKeyRequest
    CreateTenantKeyResponse:
      properties:
        key_id:
          type: string
          title: Key Id
          description: API Gateway key ID (handle used to revoke).
        tenant_id:
          type: string
          title: Tenant Id
          description: Owning tenant ID.
        tenant_name:
          type: string
          title: Tenant Name
          description: Owning tenant display name.
        tier:
          type: string
          title: Tier
          description: Usage-plan tier the key belongs to.
        api_key:
          type: string
          title: Api Key
          description: The secret API key — shown once, never retrievable again.
        created_at:
          type: string
          title: Created At
          description: Creation timestamp (ISO 8601).
        endpoint_prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint Prefix
          description: Endpoint prefix granted, if an ACL rule was created.
      type: object
      required:
      - key_id
      - tenant_id
      - tenant_name
      - tier
      - api_key
      - created_at
      title: CreateTenantKeyResponse
    DailyUsage:
      properties:
        date:
          type: string
          title: Date
          description: Day (YYYY-MM-DD).
        used:
          type: integer
          title: Used
          description: Requests consumed that day.
        remaining:
          type: integer
          title: Remaining
          description: Quota remaining after that day.
      type: object
      required:
      - date
      - used
      - remaining
      title: DailyUsage
    ErrorResponse:
      properties:
        status:
          type: string
          title: Status
          description: Always 'failed' for an error body
          default: failed
        command_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Command Name
          description: Command the request mapped to (e.g. 'centab')
        error_code:
          type: string
          title: Error Code
          description: Consumer-facing 7000000-family error code
        error_message:
          type: string
          title: Error Message
          description: Generic, source-agnostic error message
        target:
          anyOf:
          - type: string
          - type: 'null'
          title: Target
          description: Offending request field for 7000000 (e.g. 'ticker')
      type: object
      required:
      - error_code
      - error_message
      title: ErrorResponse
      description: 'Consumer-facing error body returned on any non-success.


        Carries only the BR-04-safe surface: a numeric ``7000000``-family ``error_code``,

        a generic ``error_message``, and an optional ``target`` field name. Internal
        error

        codes, storage targets, bucket names, and exception details are never included.'
    ExecuteCommandRequest:
      properties:
        command:
          type: string
          title: Command
          description: 'Command name: ''flip'', ''d'', ''volume'', ''get_company_profiles'',
            etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
          description: Stock/options ticker symbol (e.g. SPY, QQQ)
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
          description: Discord channel ID
        eval_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Eval Price
          description: Evaluation price for options calculations
        min_days:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Days
          description: Minimum days to expiration filter
        max_days:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Days
          description: Maximum days to expiration filter
        days_back:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days Back
          description: Days back for historical analysis
        start_days_back:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start Days Back
          description: Start offset for historical analysis
        test_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Date
          description: Override date for backtesting (YYYY-MM-DD)
        parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parameters
          description: Additional command parameters
      type: object
      required:
      - command
      title: ExecuteCommandRequest
    ExpiriesResponse:
      properties:
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ET ISO 8601 timestamp when this response was generated
        expiries:
          anyOf:
          - items:
              $ref: '#/components/schemas/ExpiryItem'
            type: array
          - type: 'null'
          title: Expiries
          description: Upcoming expiries with DTE and type metadata
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      title: ExpiriesResponse
      description: Expiries (D) API payload — next expiration dates for a ticker.
    ExpiryItem:
      properties:
        expiry_date:
          type: string
          title: Expiry Date
        dte:
          type: integer
          title: Dte
        expiry_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Type
      type: object
      required:
      - expiry_date
      - dte
      title: ExpiryItem
    FlipCommandRequest:
      properties:
        ticker:
          type: string
          title: Ticker
          description: Stock/options ticker symbol
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
          description: Discord channel ID
        eval_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Eval Price
          description: Evaluation price for options calculations
        min_days:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Days
          description: Minimum days to expiration filter
        max_days:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Days
          description: Maximum days to expiration filter
        tolerance:
          anyOf:
          - type: number
          - type: 'null'
          title: Tolerance
          description: Tolerance for transition calculation
        test_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Date
          description: Override date for backtesting (YYYY-MM-DD)
      type: object
      required:
      - ticker
      title: FlipCommandRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthCheckResult:
      properties:
        status:
          type: string
          title: Status
          description: '"healthy", "unhealthy", or "degraded".'
        service:
          type: string
          title: Service
          description: Stable service identifier (matches the URL segment).
        latency_ms:
          type: number
          title: Latency Ms
          description: Wall-clock latency of the probe in milliseconds.
        checked_at:
          type: string
          title: Checked At
          description: ISO-8601 UTC timestamp of when the probe ran.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Categorised error message when unhealthy; null when healthy.
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Optional probe-specific data. For grouped probes (/dynamodb,
            /s3) this is a dict of resource-name -> PerResourceHealthCheck. For single
            probes it is small free-form facts (e.g. records_retrieved).
      type: object
      required:
      - status
      - service
      - latency_ms
      - checked_at
      title: HealthCheckResult
      description: Envelope returned by every probe endpoint.
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
        service:
          type: string
          title: Service
        environment:
          anyOf:
          - type: string
          - type: 'null'
          title: Environment
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
      type: object
      required:
      - status
      - service
      title: HealthResponse
    KeyUsage:
      properties:
        key_id:
          type: string
          title: Key Id
          description: API Gateway key ID.
        key_name:
          type: string
          title: Key Name
          description: Friendly key name (empty if unresolved).
        tier:
          type: string
          title: Tier
          description: Usage-plan tier the key belongs to.
        tenant_id:
          type: string
          title: Tenant Id
          description: Owning tenant ID (empty if not tenant-bound).
          default: ''
        tenant_name:
          type: string
          title: Tenant Name
          description: Owning tenant display name (empty if not tenant-bound).
          default: ''
        total_used:
          type: integer
          title: Total Used
          description: Total requests over the window.
        quota_remaining:
          type: integer
          title: Quota Remaining
          description: Quota remaining at end of window.
        daily:
          items:
            $ref: '#/components/schemas/DailyUsage'
          type: array
          title: Daily
          description: Per-day breakdown.
      type: object
      required:
      - key_id
      - key_name
      - tier
      - total_used
      - quota_remaining
      title: KeyUsage
    RouteListResponse:
      properties:
        routes:
          items:
            $ref: '#/components/schemas/RouteListing'
          type: array
          title: Routes
      type: object
      required:
      - routes
      title: RouteListResponse
      description: Response of ``/v1/health/routes``.
    RouteListing:
      properties:
        method:
          type: string
          title: Method
          description: HTTP method (GET / POST / ...).
        path:
          type: string
          title: Path
          description: Registered route path (e.g. /v1/centab/{ticker}).
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Endpoint function name (FastAPI default).
        probed:
          type: boolean
          title: Probed
          description: True iff a SYNTHETIC_PROBES entry's payload command matches
            the route's underlying command. Informational only — does not indicate
            health.
      type: object
      required:
      - method
      - path
      - probed
      title: RouteListing
      description: Single entry in the ``/v1/health/routes`` response.
    SpecpaResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        session_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Date
          description: ET session calendar date (YYYY-MM-DD)
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ET ISO 8601 timestamp when this response was generated
        expiry_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Date
          description: 0DTE expiry date (YYYY-MM-DD) tracked in this session
        spot_last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Spot Last Updated
          description: ET ISO 8601 timestamp of the most recent snapshot in the data
        slice_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slice Count
          description: Total number of intraday percentile slices
        slices:
          anyOf:
          - items:
              $ref: '#/components/schemas/SpecpaSlice'
            type: array
          - type: 'null'
          title: Slices
          description: Per-snapshot specpa slices ordered by snapshot_timestamp
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - status
      title: SpecpaResponse
      description: Specpa API payload.
    SpecpaSlice:
      properties:
        snapshot_timestamp:
          type: string
          title: Snapshot Timestamp
        spot_price:
          type: number
          title: Spot Price
        c10:
          type: number
          title: C10
        c20:
          type: number
          title: C20
        c30:
          type: number
          title: C30
        c40:
          type: number
          title: C40
        c50:
          type: number
          title: C50
        p10:
          type: number
          title: P10
        p20:
          type: number
          title: P20
        p30:
          type: number
          title: P30
        p40:
          type: number
          title: P40
        p50:
          type: number
          title: P50
      type: object
      required:
      - snapshot_timestamp
      - spot_price
      - c10
      - c20
      - c30
      - c40
      - c50
      - p10
      - p20
      - p30
      - p40
      - p50
      title: SpecpaSlice
      description: Per-snapshot absolute percentile slice for specpa.
    TenantKeyEntry:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Owning tenant ID.
        tenant_name:
          type: string
          title: Tenant Name
          description: Owning tenant display name.
        tier:
          type: string
          title: Tier
          description: Usage-plan tier the key belongs to.
        key_id:
          type: string
          title: Key Id
          description: API Gateway key ID (handle used to revoke).
        active:
          type: boolean
          title: Active
          description: Whether the key is active.
        created_at:
          type: string
          title: Created At
          description: Creation timestamp (ISO 8601).
      type: object
      required:
      - tenant_id
      - tenant_name
      - tier
      - key_id
      - active
      - created_at
      title: TenantKeyEntry
    TenantKeyListResponse:
      properties:
        keys:
          items:
            $ref: '#/components/schemas/TenantKeyEntry'
          type: array
          title: Keys
          description: Every tenant key (metadata only; secret not included).
      type: object
      title: TenantKeyListResponse
    UpdateCircuitBreakerRequest:
      properties:
        service_name:
          type: string
          title: Service Name
        state:
          type: string
          title: State
      type: object
      required:
      - service_name
      - state
      title: UpdateCircuitBreakerRequest
    UpdateCircuitBreakerResponse:
      properties:
        service_name:
          type: string
          title: Service Name
        previous_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Previous State
        new_state:
          type: string
          title: New State
        updated:
          type: boolean
          title: Updated
      type: object
      required:
      - service_name
      - new_state
      - updated
      title: UpdateCircuitBreakerResponse
    UsageReportResponse:
      properties:
        start_date:
          type: string
          title: Start Date
          description: Window start (YYYY-MM-DD).
        end_date:
          type: string
          title: End Date
          description: Window end (YYYY-MM-DD).
        keys:
          items:
            $ref: '#/components/schemas/KeyUsage'
          type: array
          title: Keys
          description: Per-key usage, busiest first.
      type: object
      required:
      - start_date
      - end_date
      title: UsageReportResponse
    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
    VoldResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        session_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Date
          description: ET session calendar date (YYYY-MM-DD)
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ET ISO 8601 timestamp when this response was generated
        spot_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Spot Price
          description: Underlying spot price at time of data materialization
        spot_last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Spot Last Updated
          description: ET ISO 8601 timestamp of the most recent snapshot in the data
        expiry_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Date
          description: 0DTE expiry date (YYYY-MM-DD) tracked in this session
        total_oi:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Oi
          description: Total open interest (calls + puts)
        slices:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Slices
          description: Per-snapshot VOLD slices ordered by snapshot_timestamp (full
            cumulative payload only)
        snapshot_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Snapshot Timestamp
          description: Slice timestamp — populated only for /latest and /slice responses
        strikes:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Strikes
          description: Per-strike call/put volume for this slice — populated only
            for /latest and /slice responses
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - status
      title: VoldResponse
      description: 'Vold API payload.


        Volume fields (``spot_price``, ``total_oi``, ``slices``, etc.) are exposed
        only at

        the top level; there is no nested ``data`` object (handler ``result_data``
        may still

        nest under ``data`` for internal use).


        ``/vold/{ticker}`` (full cumulative payload) populates ``slices`` (a list).
        Per spec,

        ``/vold/{ticker}/latest`` and ``/vold/{ticker}/slice/{timestamp}`` instead
        return a flat

        single slice: ``snapshot_timestamp`` + ``strikes`` populated, ``slices`` left
        ``null``.'
    VolumeExpiry:
      properties:
        expiry_date:
          type: string
          title: Expiry Date
        expiry_timestamp:
          type: string
          title: Expiry Timestamp
          description: Expiry anchored to 16:00 ET (ISO 8601)
        strikes:
          items:
            $ref: '#/components/schemas/VolumeStrike'
          type: array
          title: Strikes
      type: object
      required:
      - expiry_date
      - expiry_timestamp
      - strikes
      title: VolumeExpiry
      description: One expiry's strike chain in a VOLU response.
    VolumeExpiryRangeModel:
      properties:
        min_dte:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Dte
        max_dte:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Dte
        expiry_date_from:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Date From
        expiry_date_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiry Date To
      type: object
      title: VolumeExpiryRangeModel
      description: Effective DTE bounds and expiry-date span actually covered by a
        VOLU response.
    VolumeResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Command execution status: completed, failed, etc.'
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ET ISO 8601 timestamp when this response was generated
        spot_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Spot Price
          description: Underlying spot price at time of data materialization
        spot_last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Spot Last Updated
          description: ET ISO 8601 timestamp of the most recent snapshot in the data
        expiry_range:
          anyOf:
          - $ref: '#/components/schemas/VolumeExpiryRangeModel'
          - type: 'null'
          description: Effective min/max DTE and expiry-date span covered by this
            response
        total_oi:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Oi
          description: Total open interest (calls + puts)
        expiries:
          anyOf:
          - items:
              $ref: '#/components/schemas/VolumeExpiry'
            type: array
          - type: 'null'
          title: Expiries
          description: Per-expiry strike chains, ordered by expiry_date
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - status
      title: VolumeResponse
      description: 'Volume (VOLU) API payload — multi-expiry volume, time dimension
        collapsed (Tier 3/4 §5.10).


        Fields are flat at the top level (no nested ``data`` object), matching the
        sibling

        vold/centab/specpa responses; ``result_data`` may still nest under ``data``

        internally for handler use.'
    VolumeStrike:
      properties:
        strike:
          type: number
          title: Strike
        call_volume:
          type: integer
          title: Call Volume
        put_volume:
          type: integer
          title: Put Volume
      type: object
      required:
      - strike
      - call_volume
      - put_volume
      title: VolumeStrike
      description: One strike's aggregated call/put volume within a VOLU expiry row.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Add your API key as the 'X-API-Key' header on every request.
tags: []
security:
- ApiKeyAuth: []
servers:
- url: https://stage.api.gammaedge.us
