Breeze Strategies API

openapi: 3.1.0
info:
  title: Breeze Admin Strategies API
  description: A comprehensive API for managing yield farming operations, funds, and user authentication
  contact:
    name: Breeze Team
    email: support@breeze.com
  license:
    name: Proprietary
    url: https://breeze.com/license
  version: 1.0.0
servers:
- url: http://localhost:8080
  description: Local development server
- url: https://api.breeze.com
  description: Production server
tags:
- name: Strategies
paths:
  /organization/create-strategy-template:
    post:
      tags:
      - Strategies
      operationId: create_new_strategy_template
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiInputForCreatingStrategy'
        required: true
      responses:
        '200':
          description: Strategy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCreateStrategyTemplateResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /organization/create-strategy/{organization_id}:
    post:
      tags:
      - Strategies
      operationId: create_new_strategy
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiInputForInitializingStrategy'
        required: true
      responses:
        '200':
          description: Fund created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStrategyApiResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /organization/strategies:
    get:
      tags:
      - Strategies
      operationId: get_organization_strategies
      responses:
        '200':
          description: Strategies with list metrics retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StrategyWithListMetrics'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /organization/{organization_id}/strategies:
    get:
      tags:
      - Strategies
      operationId: get_strategies
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Strategies with metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vec'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy-available-assets:
    get:
      tags:
      - Strategies
      summary: Get available strategy assets with their yield sources
      operationId: get_strategy_available_assets
      responses:
        '200':
          description: Available strategy assets with yield sources retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyAvailableAssetsResponse'
        '404':
          description: Global configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/apy:
    get:
      tags:
      - Strategies
      operationId: get_strategy_apy
      parameters:
      - name: all
        in: query
        description: To calculate combined apy for all the strategy belongs to an org
        required: true
        schema:
          type: boolean
      - name: strategy_id
        in: query
        description: To calculate apy of a single strategy
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Strategy apy retrieved successfully
        '404':
          description: Strategy not found or no data available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/close-funds:
    post:
      tags:
      - Strategies
      operationId: close_strategy_funds
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCloseStrategyFundsRequest'
        required: true
      responses:
        '200':
          description: Close fund jobs submitted successfully for all funds in strategy
        '400':
          description: Invalid strategy id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Organization access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/metrics:
    get:
      tags:
      - Strategies
      operationId: get_strategy_metrics
      parameters:
      - name: time_frame
        in: query
        description: 'Simplified time selector: ''24h'', ''7d'', ''30d'', ''all''. Backend derives start/end/aggregation automatically. Takes precedence over legacy params.'
        required: false
        schema:
          type: string
      - name: all
        in: query
        description: To calculate full overview metrics or calculate individual metrics
        required: true
        schema:
          type: boolean
      - name: strategy_id
        in: query
        description: Strategy id for getting single strategy metrics
        required: false
        schema:
          type: string
      - name: start_timestamp
        in: query
        description: 'Legacy: ISO 8601 start. Use time_frame instead.'
        required: false
        schema:
          type: string
      - name: end_timestamp
        in: query
        description: 'Legacy: ISO 8601 end. Use time_frame instead.'
        required: false
        schema:
          type: string
      - name: aggregation_window
        in: query
        description: 'Legacy: aggregation window. Use time_frame instead.'
        required: false
        schema:
          type: string
      - name: all_time
        in: query
        description: 'Legacy: fetch full history. Use time_frame=''all'' instead.'
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Strategy metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStrategyMetricUniversal'
        '400':
          description: Invalid time range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fund not found or no data available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/metrics/current-data:
    get:
      tags:
      - Strategies
      summary: 'Returns current aggregate metrics (TVL, deposits, fees, yield, per-protocol breakdowns)

        for all or a single strategy belonging to the authenticated organization.'
      description: 'All monetary values are returned in USD. Fee amounts are converted from raw token units

        using per-fund decimals and current asset prices.'
      operationId: get_strategy_current_data_for_metric
      parameters:
      - name: all
        in: query
        description: To get combied current data for all the strategy that belongs to an org
        required: true
        schema:
          type: boolean
      - name: strategy_id
        in: query
        description: Strategy id for getting current data of an individual strategy
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Strategy current data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStrategyMetricCurrentData'
        '404':
          description: Strategy not found or no data available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/strategy-latest-top-rebalance-history:
    get:
      tags:
      - Strategies
      operationId: get_strategy_latest_rebalance_history
      parameters:
      - name: all
        in: query
        description: To include all organization strategies to get the latest top 5 rebalance hisotry of the highest allocated fund per base asset
        required: true
        schema:
          type: boolean
      - name: strategy_id
        in: query
        description: To inlcude only a particular strategy to get the latest top 5 rebalance hisotry of the highest allocated fund per base asset
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Strategy latest rebalance history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/ApiRebalanceHistory'
                propertyNames:
                  type: string
        '404':
          description: Strategy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/update-delegated-withdrawer:
    post:
      tags:
      - Strategies
      operationId: update_withdraw_delegate_authority
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateStrategyDelegatedWithdrawerRequest'
        required: true
      responses:
        '200':
          description: Delegated withdrawer update jobs submitted successfully
        '400':
          description: Invalid strategy or delegated withdrawer pubkey
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Organization access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/{strategy_id}:
    get:
      tags:
      - Strategies
      operationId: get_strategy
      parameters:
      - name: strategy_id
        in: path
        description: Strategy identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Strategy with detailed metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyDetailResponse'
        '404':
          description: Strategy not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
    put:
      tags:
      - Strategies
      operationId: update_strategy
      parameters:
      - name: strategy_id
        in: path
        description: Strategy identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiInputForUpdatingStrategyInstance'
        required: true
      responses:
        '200':
          description: Strategy updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyInstance'
        '404':
          description: Strategy not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /strategy/{strategy_id}/metrics-old:
    get:
      tags:
      - Strategies
      operationId: get_strategy_metrics_old
      parameters:
      - name: start_timestamp
        in: query
        description: Start timestamp for metrics range (ISO 8601 format)
        required: true
        schema:
          type: string
      - name: end_timestamp
        in: query
        description: End timestamp for metrics range (ISO 8601 format)
        required: true
        schema:
          type: string
      - name: aggregation_window
        in: query
        description: Optional aggregation window (e.g., '1h', '1d', '5m') - if not provided, database will choose optimal window
        required: false
        schema:
          type: string
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Strategy metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStrategyMetrics'
        '400':
          description: Invalid time range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fund not found or no data available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /template/{template_id}:
    get:
      tags:
      - Strategies
      operationId: get_template
      parameters:
      - name: template_id
        in: path
        description: Strategy template identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Strategy template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStrategyTemplate'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
components:
  schemas:
    ApiInputForInitializingStrategy:
      type: object
      required:
      - name
      - template_id
      - fee_recipient
      - fee_percentage
      - frequency_seconds
      properties:
        delegated_withdrawer:
          type:
          - string
          - 'null'
          description: Optional delegated withdraw authority applied to each fund created for this strategy.
        description:
          type:
          - string
          - 'null'
        fee_percentage:
          type: number
          format: double
        fee_recipient:
          type: string
        frequency_seconds:
          type: integer
          format: int64
          minimum: 0
        name:
          type: string
        squads_usage:
          type: boolean
          description: Optional, if the user uses squads multisig / grid
        template_id:
          type: string
    ApiStrategyMetricCurrentData:
      type: object
      required:
      - total_deposit
      - total_strategy
      - tvl
      - yield_earnings
      - strategy_user_count
      - total_deposits_in_karmino
      - total_deposits_in_drift_lending
      - total_deposits_in_marginfi
      - total_deposits_in_jup_lend
      - total_earnings_in_fees
      properties:
        strategy_user_count:
          type: integer
          minimum: 0
        total_deposit:
          type: number
          format: double
        total_deposits_in_drift_lending:
          type: number
          format: double
        total_deposits_in_jup_lend:
          type: number
          format: double
        total_deposits_in_karmino:
          type: number
          format: double
        total_deposits_in_marginfi:
          type: number
          format: double
        total_earnings_in_fees:
          type: number
          format: double
        total_strategy:
          type: integer
          format: int32
          minimum: 0
        tvl:
          type: number
          format: double
        yield_earnings:
          type: number
          format: double
    ApiStrategyFee:
      type: object
      required:
      - fee_type
      - percentage
      - recipient
      - frequency_seconds
      properties:
        fee_type:
          type: string
        frequency_seconds:
          type: integer
          format: int64
          minimum: 0
        percentage:
          type: number
          format: double
        recipient:
          type: string
    ApiRebalanceInstruction:
      type: object
      required:
      - yield_source_type
      - protocol
      - position_id
      - amount
      properties:
        amount:
          type: integer
          format: int64
        position_id:
          type: string
        protocol:
          type: string
        yield_source_type:
          type: string
    ApiUpdateStrategyDelegatedWithdrawerRequest:
      type: object
      required:
      - strategy_id
      properties:
        delegated_withdrawer:
          type:
          - string
          - 'null'
          description: Set to `null` to clear the delegated withdrawer on every fund in the strategy.
        strategy_id:
          type: string
    ApiInputForCreatingStrategy:
      type: object
      required:
      - name
      - visibility_tags
      - assets
      - fees
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/ApiTemplateAsset'
        description:
          type:
          - string
          - 'null'
        fees:
          type: array
          items:
            $ref: '#/components/schemas/ApiStrategyFee'
        name:
          type: string
        visibility_tags:
          type: array
          items:
            type: string
    StrategyAvailableAsset:
      type: object
      required:
      - token_info
      properties:
        token_info:
          $ref: '#/components/schemas/CodexToken'
        yield_sources:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ApiSelectiveYieldSource'
    FeeInfoForStrategy:
      type: object
      required:
      - fee_bps
      - fee_recipient
      - frequency_seconds
      - fee_type
      properties:
        fee_bps:
          type: integer
          format: int32
          minimum: 0
        fee_recipient:
          type: string
        fee_type:
          type: string
        frequency_seconds:
          type: integer
          format: int64
          minimum: 0
    ApiSelectiveYieldSource:
      type: object
      properties:
        drift_lending:
          type:
          - string
          - 'null'
        jup_lend:
          type:
          - string
          - 'null'
        kamino:
          type:
          - string
          - 'null'
        marginfiv2:
          type:
          - string
          - 'null'
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message description
    ApiCloseStrategyFundsRequest:
      type: object
      required:
      - strategy_id
      properties:
        strategy_id:
          type: string
    ApiInputForUpdatingStrategyInstance:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: New name for the strategy (optional)
    CreateStrategyApiResult:
      type: object
      required:
      - task_id_for_creating_all_funds
      - status
      - message
      properties:
        message:
          type: string
        status:
          type: string
        strategy_id:
          type:
          - string
          - 'null'
        task_id_for_creating_all_funds:
          type: string
    StrategyInstance:
      type: object
      required:
      - id
      - org_id
      - name
      - template_id
      - funds
      - fee_info
      - created_at
      - updated_at
      properties:
        created_at:
          type: integer
          format: int64
          minimum: 0
        description:
          type:
          - string
          - 'null'
        fee_info:
          type: array
          items:
            $ref: '#/components/schemas/FeeInfoForStrategy'
        funds:
          type: array
          items:
            $ref: '#/components/schemas/FundRef'
        id:
          type: string
        name:
          type: string
        org_id:
          type: string
        status:
          $ref: '#/components/schemas/StrategyInstanceStatus'
        template_id:
          type: string
        updated_at:
          type: integer
          format: int64
          minimum: 0
    ApiStrategyMetricUniversal:
      type: object
      required:
      - start
      - end
      - aggregation_window
      - strategy_id
      - data
      - combined_asset_value_over_time
      - per_asset_value_over_time
      - fee_distribution_metrics
      properties:
        aggregation_window:
          type: string
          description: Aggregation window (e.g., "1h", "1d", "5m") representing time between data points
        combined_asset_value_over_time:
          type: array
          items:
            $ref: '#/components/schemas/CombinedAssetValueOverTime'
        data:
          type: array
          items:
            $ref: '#/components/schemas/UniversalStrategyMetrics'
          description: Array of aggregated metric data points
        end:
          type: string
          description: End timestamp of the data range
        fee_distribution_metrics:
          type: array
          items:
            $ref: '#/components/schemas/ApiDailyFeeDistribution'
        per_asset_value_over_time:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/AssetValuePair'
          propertyNames:
            type: string
        start:
          type: string
          description: Start timestamp of the data range
        strategy_id:
          type: array
          items:
            type: string
          description: Strategy ID for the metrics
    AssetValuePair:
      type: object
      required:
      - time
      - asset
      - usd_value
      - value_in_base_asset
      properties:
        asset:
          type: string
        fund_id:
          type:
          - string
          - 'null'
        time:
          type: string
        usd_value:
          type: number
          format: double
        value_in_base_asset:
          type: number
          format: double
    CurrentStrategyData:
      type: object
      required:
      - current_usd_value
      - total_users
      - apy
      - net_yield
      - total_deposits_usd
      - current_earnings_usd
      - risk
      - protocol_values
      - average_strategy_rebalance_cadence
      properties:
        apy:
          type: number
          format: double
        average_strategy_rebalance_cadence:
          type: integer
          format: int64
          minimum: 0
        current_earnings_usd:
          type: number
          format: double
        current_usd_value:
          type: number
          format: double
        net_yield:
          type: number
          format: double
        protocol_values:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolValues'
        risk:
          type: number
          format: double
        total_deposits_usd:
          type: number
          format: double
        total_users:
          type: integer
          format: int64
          minimum: 0
    ApiDailyFeeDistribution:
      type: object
      required:
      - time
      - total_amount_distributed
      properties:
        time:
          type: string
        total_amount_distributed:
          type: number
          format: double
    FundRef:
      type: object
      required:
      - mint
      - fund_id
      properties:
        allocation_percent:
          type:
          - number
          - 'null'
          format: double
        fund_id:
          type: string
        mint:
          type: string
    CombinedAssetValueOverTime:
      type: object
      required:
      - time
      - assets
      properties:
        assets:
          type: object
          additionalProperties:
            type: number
            format: double
          propertyNames:
            type: string
        time:
          type: string
    StrategyDetailResponse:
      allOf:
      - $ref: '#/components/schemas/StrategyInstance'
        description: The full strategy instance data
      - type: object
        required:
        - apy
        - protocol_allocations
        properties:
          apy:
            type: number
            format: double
            description: Computed APY (average of non-zero yield source APYs across allocations)
          protocol_allocations:
            type: array
            items:
              $ref: '#/components/schemas/ProtocolValues'
      description: Detailed strategy response with all computed metrics (optimized batch queries)
    StrategyAvailableAssetsResponse:
      type: object
      required:
      - assets
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/StrategyAvailableAsset'
          description: List of available strategy assets with their yield sources
    ApiTemplateYieldSource:
      type: object
      properties:
        drift_lending:
          type:
          - string
          - 'null'
        jup_lend:
          type:
          - string
          - 'null'
        kamino:
          type:
          - string
          - 'null'
        marginfiv2:
          type:
          - string
          - 'null'
    Vec:
      type: array
      items:
        allOf:
        - $ref: '#/components/schemas/StrategyInstance'
          description: The full strategy instance data
        - type: object
          required:
          - apy
          - total_users
          properties:
            apy:
              type: number
              format: double
              description: Weighted APY of the strategy (from latest snapshot, may be stale). Defaults to 0 if no snapshot.
            total_users:
              type: integer
              format: int64
              description: Total unique users in the strategy (from latest snapshot, may be stale). Defaults to 0 if no snapshot.
              minimum: 0
        description: Strategy with pre-computed metrics for list views (avoids N+1 queries)
    StrategyInstanceStatus:
      type: string
      enum:
      - active
      - pending
      - failed
      - updating
    ApiTemplateAsset:
      type: object
      required:
      - mint
      - yield_sources
      properties:
        mint:
          type: string
        yield_sources:
          $ref: '#/components/schemas/ApiTemplateYieldSource'
    StrategyWithListMetrics:
      allOf:
      - $ref: '#/components/schemas/StrategyInstance'
        description: The full strategy instance data
      - type: object
        required:
        - apy
        - total_users
        - tvl_usd
        - fees_collected_usd
        properties:
          apy:
            type: number
            format: double
            description: Weighted APY of the strategy.
          fees_collected_usd:
            type: number
            format: double
            description: Total fees collected (sum of amount_distributed) across all funds in the strategy.
          total_users:
            type: integer
            format: int64
            description: Total unique users in the strategy.
            minimum: 0
          tvl_usd:
            type: number
            format: double
            description: Total value locked in USD across all funds in the strategy.
      description: Strategy with full list metrics (TVL, fees, APY, users) fo

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/breeze/refs/heads/main/openapi/breeze-strategies-api-openapi.yml