openapi: 3.1.0
info:
  title: Level2 TradeStation Integration API
  description: >-
    The Level2 TradeStation Integration API enables broker partners to embed
    the Level2 visual strategy builder into their trading platforms and manage
    user strategies programmatically. This API connects the Level2 no-code
    strategy builder with TradeStation Securities brokerage accounts, allowing
    traders to create automated strategies using a drag-and-drop interface and
    execute them in real time through their TradeStation accounts. The API
    supports strategy lifecycle management including creation, retrieval,
    updating, deployment, and deletion of user strategies, as well as
    backtesting against historical market data.
  version: '1.0.0'
  contact:
    name: Level2 Broker Support
    url: https://learn.trylevel2.com/docs/category/brokers
  termsOfService: https://www.trylevel2.com/terms-and-conditions
externalDocs:
  description: Level2 Broker API Documentation
  url: https://learn.trylevel2.com/docs/Broker/API/update-user-strategy
servers:
  - url: https://api.trylevel2.com/v1
    description: Production Server
tags:
  - name: Backtesting
    description: >-
      Endpoints for running backtests on strategies against historical market
      data to validate performance before live deployment.
  - name: Strategies
    description: >-
      Endpoints for managing user trading strategies, including creation,
      retrieval, updating, deployment, and deletion of automated trading
      strategies built with the Level2 visual strategy builder.
  - name: Users
    description: >-
      Endpoints for managing broker user accounts and their association with
      the Level2 platform.
security:
  - bearerAuth: []
paths:
  /broker/users:
    post:
      operationId: createBrokerUser
      summary: Create a broker user
      description: >-
        Creates a new user account within the Level2 platform associated with
        the broker's integration. This links a broker customer to the Level2
        strategy builder, enabling them to create and manage automated trading
        strategies.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - user already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}:
    get:
      operationId: getBrokerUser
      summary: Get a broker user
      description: >-
        Retrieves the details of a specific broker user account on the Level2
        platform, including their account status and associated configuration.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}/strategies:
    get:
      operationId: listUserStrategies
      summary: List user strategies
      description: >-
        Retrieves all trading strategies associated with the specified broker
        user. Returns both active and inactive strategies created through the
        Level2 visual strategy builder.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - name: status
          in: query
          required: false
          description: >-
            Filter strategies by their current status.
          schema:
            type: string
            enum:
              - active
              - inactive
              - deployed
              - draft
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of strategies to return per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: offset
          in: query
          required: false
          description: >-
            Number of strategies to skip for pagination.
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Strategies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyListResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createUserStrategy
      summary: Create a user strategy
      description: >-
        Creates a new trading strategy for the specified broker user. The
        strategy is initialized in draft status and can be configured with
        trading rules, conditions, and parameters using the strategy definition
        format from the Level2 visual builder.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStrategyRequest'
      responses:
        '201':
          description: Strategy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '400':
          description: Invalid strategy definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}/strategies/{strategyId}:
    get:
      operationId: getUserStrategy
      summary: Get a user strategy
      description: >-
        Retrieves the full details of a specific trading strategy including its
        configuration, status, performance metrics, and deployment state.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      responses:
        '200':
          description: Strategy retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateUserStrategy
      summary: Update a user strategy
      description: >-
        Updates an existing trading strategy for the specified user. This
        endpoint can modify the strategy definition, parameters, and metadata.
        It can also be used to soft-delete or restore a strategy by updating
        its status.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStrategyRequest'
      responses:
        '200':
          description: Strategy updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '400':
          description: Invalid strategy definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteUserStrategy
      summary: Delete a user strategy
      description: >-
        Deletes or soft-deletes a user's trading strategy. Once deleted, the
        strategy is deactivated and any live deployments are stopped. Depending
        on configuration, the strategy may be recoverable through an update
        operation.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      responses:
        '200':
          description: Strategy deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}/strategies/{strategyId}/deploy:
    post:
      operationId: deployUserStrategy
      summary: Deploy a user strategy
      description: >-
        Deploys a trading strategy for live execution through the user's
        connected TradeStation brokerage account. The strategy must be in an
        active or draft state and have a valid configuration. Once deployed,
        the strategy will monitor market conditions and execute trades
        automatically based on its defined rules.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployStrategyRequest'
      responses:
        '200':
          description: Strategy deployed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '400':
          description: Strategy cannot be deployed in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}/strategies/{strategyId}/stop:
    post:
      operationId: stopUserStrategy
      summary: Stop a deployed strategy
      description: >-
        Stops a currently deployed trading strategy, halting all automated
        trade execution. The strategy returns to an active state and can be
        redeployed later. Any open positions created by the strategy are not
        automatically closed.
      tags:
        - Strategies
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      responses:
        '200':
          description: Strategy stopped successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyResponse'
        '400':
          description: Strategy is not currently deployed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /broker/users/{userId}/strategies/{strategyId}/backtest:
    post:
      operationId: backtestUserStrategy
      summary: Backtest a user strategy
      description: >-
        Runs a backtest on the specified strategy against historical market
        data for the configured instruments and date range. Returns performance
        metrics including profit and loss, win rate, maximum drawdown, Sharpe
        ratio, and trade-by-trade results. Backtesting enables traders to
        validate strategy effectiveness before deploying with real capital.
      tags:
        - Backtesting
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/strategyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BacktestRequest'
      responses:
        '200':
          description: Backtest completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BacktestResponse'
        '400':
          description: Invalid backtest parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Strategy or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication for broker API access. Tokens are issued
        to broker partners during the integration onboarding process.
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: >-
        The unique identifier of the broker user on the Level2 platform.
      schema:
        type: string
    strategyId:
      name: strategyId
      in: path
      required: true
      description: >-
        The unique identifier of the trading strategy.
      schema:
        type: string
  schemas:
    CreateUserRequest:
      type: object
      description: Request body for creating a new broker user account.
      required:
        - externalId
      properties:
        externalId:
          type: string
          description: >-
            The broker's external identifier for this user, used to link the
            Level2 account to the broker's customer record.
        email:
          type: string
          format: email
          description: The user's email address
        displayName:
          type: string
          description: The user's display name shown in the Level2 interface
          maxLength: 100
    UserResponse:
      type: object
      description: Response containing user account details.
      properties:
        id:
          type: string
          description: The unique Level2 user identifier
        externalId:
          type: string
          description: The broker's external identifier for this user
        email:
          type: string
          format: email
          description: The user's email address
        displayName:
          type: string
          description: The user's display name
        status:
          type: string
          description: The current account status
          enum:
            - active
            - inactive
            - suspended
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user account was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the user account was last updated
    CreateStrategyRequest:
      type: object
      description: >-
        Request body for creating a new trading strategy. Includes the strategy
        metadata and its visual builder definition.
      required:
        - name
        - instrument
      properties:
        name:
          type: string
          description: A human-readable name for the strategy
          maxLength: 200
        description:
          type: string
          description: A description of what the strategy does
          maxLength: 2000
        instrument:
          type: string
          description: >-
            The ticker symbol of the primary instrument this strategy trades
          example: AAPL
        instrumentType:
          type: string
          description: The type of financial instrument
          enum:
            - stock
            - option
            - future
        timeframe:
          type: string
          description: The primary chart timeframe for the strategy
          enum:
            - 1m
            - 5m
            - 15m
            - 30m
            - 1h
            - 4h
            - 1d
        definition:
          $ref: '#/components/schemas/StrategyDefinition'
    UpdateStrategyRequest:
      type: object
      description: >-
        Request body for updating an existing trading strategy.
      properties:
        name:
          type: string
          description: Updated name for the strategy
          maxLength: 200
        description:
          type: string
          description: Updated description
          maxLength: 2000
        instrument:
          type: string
          description: Updated ticker symbol
        instrumentType:
          type: string
          description: Updated instrument type
          enum:
            - stock
            - option
            - future
        timeframe:
          type: string
          description: Updated chart timeframe
          enum:
            - 1m
            - 5m
            - 15m
            - 30m
            - 1h
            - 4h
            - 1d
        status:
          type: string
          description: >-
            Updated strategy status. Set to inactive to soft-delete, or active
            to restore a soft-deleted strategy.
          enum:
            - active
            - inactive
            - draft
        definition:
          $ref: '#/components/schemas/StrategyDefinition'
    StrategyResponse:
      type: object
      description: >-
        Response containing full strategy details including configuration,
        status, and performance information.
      properties:
        id:
          type: string
          description: The unique strategy identifier
        userId:
          type: string
          description: The owner user identifier
        name:
          type: string
          description: The strategy name
        description:
          type: string
          description: The strategy description
        instrument:
          type: string
          description: The primary instrument ticker symbol
        instrumentType:
          type: string
          description: The instrument type
          enum:
            - stock
            - option
            - future
        timeframe:
          type: string
          description: The primary chart timeframe
        status:
          type: string
          description: The current strategy status
          enum:
            - draft
            - active
            - deployed
            - inactive
        definition:
          $ref: '#/components/schemas/StrategyDefinition'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the strategy was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the strategy was last updated
        deployedAt:
          type: string
          format: date-time
          description: Timestamp when the strategy was last deployed
    StrategyListResponse:
      type: object
      description: Paginated list of user strategies.
      properties:
        strategies:
          type: array
          description: List of strategy objects
          items:
            $ref: '#/components/schemas/StrategyResponse'
        total:
          type: integer
          description: Total number of strategies matching the filter
        limit:
          type: integer
          description: Maximum number of results per page
        offset:
          type: integer
          description: Current offset for pagination
    StrategyDefinition:
      type: object
      description: >-
        The visual strategy builder definition containing entry conditions,
        exit conditions, and risk management rules created through the Level2
        drag-and-drop interface.
      properties:
        entryConditions:
          type: array
          description: >-
            List of conditions that must be met to trigger a trade entry
          items:
            $ref: '#/components/schemas/StrategyCondition'
        exitConditions:
          type: array
          description: >-
            List of conditions that trigger trade exits
          items:
            $ref: '#/components/schemas/StrategyCondition'
        riskManagement:
          $ref: '#/components/schemas/RiskManagement'
        position:
          $ref: '#/components/schemas/PositionConfig'
    StrategyCondition:
      type: object
      description: >-
        A single condition in a trading strategy, representing a comparison
        between indicators, price values, or other market data points.
      properties:
        id:
          type: string
          description: Unique identifier for this condition
        indicator:
          type: string
          description: >-
            The technical indicator or data source for the left side of the
            condition (e.g., SMA, RSI, MACD, Price)
        parameters:
          type: object
          description: >-
            Parameters for the indicator (e.g., period length, source field)
          additionalProperties: true
        operator:
          type: string
          description: The comparison operator
          enum:
            - crosses_above
            - crosses_below
            - greater_than
            - less_than
            - equals
        compareValue:
          description: >-
            The value or indicator to compare against (right side of condition)
          oneOf:
            - type: number
            - type: string
            - type: object
        logicalOperator:
          type: string
          description: >-
            How this condition combines with the next condition in the list
          enum:
            - AND
            - OR
    RiskManagement:
      type: object
      description: >-
        Risk management configuration for the strategy including stop loss,
        take profit, and trailing stop settings.
      properties:
        stopLoss:
          type: number
          format: float
          description: Stop loss percentage or absolute value
        stopLossType:
          type: string
          description: Whether stop loss is a percentage or absolute price
          enum:
            - percentage
            - absolute
        takeProfit:
          type: number
          format: float
          description: Take profit percentage or absolute value
        takeProfitType:
          type: string
          description: Whether take profit is a percentage or absolute price
          enum:
            - percentage
            - absolute
        trailingStop:
          type: number
          format: float
          description: Trailing stop distance percentage
        maxPositions:
          type: integer
          description: Maximum number of concurrent open positions
          minimum: 1
    PositionConfig:
      type: object
      description: >-
        Position sizing and order configuration for the strategy.
      properties:
        side:
          type: string
          description: The trade direction
          enum:
            - long
            - short
            - both
        orderType:
          type: string
          description: The order type used for entries
          enum:
            - market
            - limit
            - stop
        quantity:
          type: number
          format: float
          description: The number of shares or contracts per trade
        quantityType:
          type: string
          description: Whether quantity is shares, contracts, or a dollar amount
          enum:
            - shares
            - contracts
            - dollars
    DeployStrategyRequest:
      type: object
      description: >-
        Optional deployment configuration for a strategy being activated for
        live trading.
      properties:
        paperTrading:
          type: boolean
          description: >-
            Whether to deploy in paper trading mode (simulated) rather than
            live trading. Defaults to false.
          default: false
    BacktestRequest:
      type: object
      description: >-
        Request body specifying the parameters for a strategy backtest run.
      required:
        - startDate
        - endDate
      properties:
        startDate:
          type: string
          format: date
          description: The start date for the backtest period
        endDate:
          type: string
          format: date
          description: The end date for the backtest period
        initialCapital:
          type: number
          format: float
          description: The starting capital amount for the backtest in USD
          default: 100000
          minimum: 0
        commissionPerTrade:
          type: number
          format: float
          description: Commission cost per trade in USD
          default: 0
          minimum: 0
    BacktestResponse:
      type: object
      description: >-
        Response containing the results of a strategy backtest including
        performance metrics and trade history.
      properties:
        strategyId:
          type: string
          description: The strategy that was backtested
        startDate:
          type: string
          format: date
          description: The start date of the backtest period
        endDate:
          type: string
          format: date
          description: The end date of the backtest period
        initialCapital:
          type: number
          format: float
          description: The starting capital used in the backtest
        finalCapital:
          type: number
          format: float
          description: The ending capital after the backtest
        totalReturn:
          type: number
          format: float
          description: Total return as a decimal (e.g., 0.15 for 15%)
        totalTrades:
          type: integer
          description: Total number of trades executed during the backtest
        winningTrades:
          type: integer
          description: Number of profitable trades
        losingTrades:
          type: integer
          description: Number of losing trades
        winRate:
          type: number
          format: float
          description: Win rate as a decimal between 0 and 1
          minimum: 0
          maximum: 1
        maxDrawdown:
          type: number
          format: float
          description: Maximum drawdown as a decimal
        sharpeRatio:
          type: number
          format: float
          description: Sharpe ratio of the strategy returns
        profitFactor:
          type: number
          format: float
          description: Ratio of gross profits to gross losses
        trades:
          type: array
          description: Detailed list of individual trades executed
          items:
            $ref: '#/components/schemas/BacktestTrade'
    BacktestTrade:
      type: object
      description: A single trade executed during a backtest.
      properties:
        entryDate:
          type: string
          format: date-time
          description: Timestamp when the trade was entered
        exitDate:
          type: string
          format: date-time
          description: Timestamp when the trade was exited
        side:
          type: string
          description: The trade direction
          enum:
            - long
            - short
        entryPrice:
          type: number
          format: float
          description: The price at which the trade was entered
        exitPrice:
          type: number
          format: float
          description: The price at which the trade was exited
        quantity:
          type: number
          format: float
          description: The number of shares or contracts traded
        pnl:
          type: number
          format: float
          description: The profit or loss for this trade in USD
        returnPct:
          type: number
          format: float
          description: The return percentage for this trade
        exitReason:
          type: string
          description: The reason the trade was exited
          enum:
            - take_profit
            - stop_loss
            - trailing_stop
            - exit_condition
            - end_of_backtest
    ErrorResponse:
      type: object
      description: Standard error response for broker API requests.
      properties:
        error:
          type: string
          description: A human-readable error message
        code:
          type: string
          description: A machine-readable error code
        details:
          type: object
          description: Additional error details when available
          additionalProperties: true