Clear Street Studio API

openapi: 3.0.0
info:
  title: Common API Models
  description: Common API models for all of Studio's APIs
  version: 2.0.0
servers:
  - url: https://api.clearstreet.io/studio/v2
    description: Production environment
  - url: https://sandbox-api.clearstreet.io/studio/v2
    description: Sandbox environment
tags:
  - name: Performance
    x-displayName: Performance
  - name: Holdings
    x-displayName: Holdings
  - name: Orders
    x-displayName: Orders
  - name: Trades
    x-displayName: Trades
  - name: Positions
    x-displayName: Positions
  - name: Locates
    x-displayName: Locates
  - name: Rates
    x-displayName: Rates
  - name: Inventories
    x-displayName: Inventories
  - name: Entities
    x-displayName: Entities
  - name: Accounts
    x-displayName: Accounts
  - name: Instruments
    x-displayName: Instruments
  - name: PNL
    x-displayName: PNL
  - name: Margin
    x-displayName: Margin
  - name: Margin Simulations
    x-displayName: Margin Simulations
externalDocs:
  url: https://docs.clearstreet.io/
paths:
  /accounts/{account_id}/pnl-sums:
    get:
      operationId: listPNLSums
      summary: List PNL Sums
      description: >-
        List historical PNL summations for a given account over a given date range, filtered on the given
        query parameters.
      tags:
        - Performance
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list PNL sums for.
        - in: query
          name: starting_date
          required: true
          schema:
            $ref: '#/components/schemas/Date'
            description: The starting date to accumulate PNL data for.
        - in: query
          name: ending_date
          required: true
          schema:
            $ref: '#/components/schemas/Date'
            description: The ending date to accumulate PNL data for, inclusive.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  starting_date:
                    $ref: '#/components/schemas/Date'
                    description: Echoed back from the provided query param.
                  ending_date:
                    $ref: '#/components/schemas/Date'
                    description: Echoed back from the provided query param.
                  entity_id:
                    $ref: '#/components/schemas/EntityId'
                  account_id:
                    $ref: '#/components/schemas/AccountId'
                  account_number:
                    $ref: '#/components/schemas/AccountNumber'
                  starting_equity:
                    type: number
                    format: double
                    description: >-
                      The equity at the start of the date range. Start of day equity of the starting date in
                      the date range.
                  ending_equity:
                    type: number
                    format: double
                    description: >-
                      The equity at the end of the date range. End of day equity of the ending date in the
                      date range.
                  day_pnl:
                    type: number
                    format: double
                    description: >-
                      Sum of profit and loss from intraday trading activities for the given date range across
                      all symbols.
                  position_pnl:
                    type: number
                    format: double
                    description: Sum of profit and loss from previous trading date across all symbols.
                  unrealized_pnl:
                    type: number
                    format: double
                    description: Sum of profit and loss from market changes across all symbols.
                  realized_pnl:
                    type: number
                    format: double
                    description: >-
                      Sum of profit and loss realized from position closing trading activity across all
                      symbols.
                  total_pnl:
                    type: number
                    format: double
                    description: |
                      `realized_pnl + unrealized_pnl`
                  net_pnl:
                    type: number
                    format: double
                    description: >
                      `P&L after netting all realized and unrealized P&L, adjustments, dividends, change in
                      accruals, income and expenses`
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PnlSum'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/holdings:
    get:
      operationId: listHoldings
      summary: List holdings
      description: >-
        List holdings for a given account, filtered on the given query parameters. This endpoint will return
        either historical or real-time holdings directly from our custodial systems. Positions returned here
        are can be different than positions returned from the Execution API. While the Execution API returns
        positions based on trading activity within Studio, our custodial system returns all positions
        regardless of where trades occur.
      tags:
        - Holdings
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list holdings for.
        - in: query
          name: date
          schema:
            $ref: '#/components/schemas/Date'
            description: >-
              The historical date to get holdings for. If omitted, current real-time holdings will be
              returned.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    $ref: '#/components/schemas/AccountId'
                  account_number:
                    $ref: '#/components/schemas/AccountNumber'
                  date:
                    $ref: '#/components/schemas/Date'
                  sod_equity:
                    type: number
                    format: double
                    description: Start of day equity.
                  eod_equity:
                    type: number
                    format: double
                    description: For historical holdings, the end of day equity. Omitted for real-time holdings.
                  timestamp:
                    $ref: '#/components/schemas/Timestamp'
                    description: >-
                      For real-time holdings, the timestamp reflecting the last update made to the holdings
                      data. Omitted for historical holdings.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Holding'
                required:
                  - account_id
                  - account_number
                  - date
                  - sod_equity
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/bulk-orders:
    post:
      operationId: createBulkOrders
      summary: Create bulk orders
      description: >
        Creates multiple orders in a single request, up to 1000. Note that a successful call to this endpoint
        does not necessarily mean your orders have been accepted, e.g. a downstream venue might reject your
        order. You should therefore utilize our WebSocket APIs to listen for changes in order lifecycle
        events.


        The response will contain an array of objects, indicating whether your order was submitted. If the
        order was submitted, the `order_id` field will be populated with the order ID assigned to this order.
        If the order was rejected, the `reason` field will be populated with the reason for rejection. The
        data array returned in the response object is guaranteed to be ordered in the same order as the orders
        you provided in the request. Again, note that even if your order was submitted, that doesn't mean it
        was _accepted_, and may still be rejected by downstream venues.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to create orders for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orders:
                  type: array
                  description: An array of orders to create.
                  items:
                    $ref: '#/components/schemas/CreateOrder'
                  minItems: 1
                  maxItems: 1000
              required:
                - orders
              additionalProperties: false
      responses:
        '201':
          description: Orders received. Indicates the orders were received and are pending further processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  submitted:
                    type: integer
                    description: Total number of orders submitted
                  rejected:
                    type: integer
                    description: Total number of orders rejected
                  data:
                    type: array
                    description: >-
                      Array indicating whether each respective order was submitted or not. This array is
                      guaranteed to be sorted in the same order as the orders you provided in your request.
                    items:
                      type: object
                      properties:
                        submitted:
                          type: boolean
                          description: True if the order was submitted successfully, false otherwise.
                        order_id:
                          $ref: '#/components/schemas/OrderId'
                          description: >-
                            If the order was submitted, the order ID assigned to this order. Empty if the
                            order was rejected.
                        reason:
                          type: string
                          description: If the order rejected, the reason for rejection. Empty if the order was accepted.
                      required:
                        - submitted
                required:
                  - submitted
                  - rejected
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/orders:
    post:
      operationId: createOrder
      summary: Create order
      description: >-
        Creates a new order and sends to our internal systems for execution. Note that a successful call to
        this endpoint does not necessarily mean your order has been accepted, e.g. a downstream venue might
        reject your order. You should therefore utilize our WebSocket APIs to listen for changes in order
        lifecycle events.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to create the order for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '201':
          description: Order received. Indicates the the order was received and is pending further processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                    example: 234usdfa3
                    description: An internally generated unique ID for this order.
                required:
                  - order_id
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
    get:
      operationId: listOrders
      summary: List orders
      description: List orders for a given account for the current trading day, filtered on the given query parameters.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list orders for.
        - in: query
          name: from
          schema:
            $ref: '#/components/schemas/Timestamp'
            description: >-
              Milliseconds since epoch timestamp. This will constrain the search for orders created after this
              timestamp, inclusively. Timestamps for orders prior the current trading day will be ignored.
        - in: query
          name: to
          schema:
            $ref: '#/components/schemas/Timestamp'
            description: >-
              Milliseconds since epoch timestamp. This will constrain the search for orders created before
              this timestamp, inclusively. Timestamps for orders beyond the current trading day will be
              ignored.
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            maximum: 2000
            default: 25
            description: Number of orders to return per page.
        - in: query
          name: page_token
          schema:
            type: string
            description: Cursor for the page to return.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  next_page_token:
                    type: string
                    description: Cursor for the next page of results.
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
    delete:
      operationId: deleteAllOrders
      summary: Delete all orders
      description: >-
        Attempts to cancel all open orders for a given account. Cancelling an order cannot be guaranteed as
        there might be in-flight executions.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to cancel orders for.
        - in: query
          name: symbol
          schema:
            $ref: '#/components/schemas/Symbol'
            description: >-
              Cancel orders only for this specific symbol. If this is omitted, all open orders will be
              cancelled.
        - in: query
          name: symbol_format
          schema:
            $ref: '#/components/schemas/SymbolFormat'
            default: cms
            description: Format of the provided symbol.
      responses:
        '201':
          description: Successfully attempted to cancel all open orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderId'
                    description: Array of order IDs that were attempted to be cancelled.
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/orders/{order_id}:
    get:
      operationId: getOrder
      summary: Get order
      description: Get an order that was previously created.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to get the order for.
        - in: path
          name: order_id
          required: true
          schema:
            $ref: '#/components/schemas/OrderId'
      responses:
        '200':
          description: The order associated with the given `order_id`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
                required:
                  - order
                additionalProperties: false
      security:
        - BearerAuth: []
    delete:
      operationId: deleteOrder
      summary: Delete order
      description: >-
        Attempts to cancel an existing order. Cancelling an order cannot be guaranteed as there might be
        in-flight executions.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to attempt to cancel the order for.
        - in: path
          name: order_id
          required: true
          schema:
            $ref: '#/components/schemas/OrderId'
      responses:
        '201':
          description: Order cancel successfully attempted.
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
    patch:
      operationId: updateOrder
      summary: Update order
      description: >-
        Attempts to update an existing order. This can be used to update a subset of an order's attributes,
        for example price and quantity.
      tags:
        - Orders
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to attempt to update the order for.
        - in: path
          name: order_id
          required: true
          schema:
            $ref: '#/components/schemas/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrder'
      responses:
        '201':
          description: Order update successfully attempted.
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/trades/{trade_id}:
    get:
      operationId: getTrade
      summary: Get trade
      description: Get trade a trade by its unique trade ID.
      tags:
        - Trades
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to get the trade for.
        - in: path
          name: trade_id
          required: true
          schema:
            $ref: '#/components/schemas/TradeId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/trades:
    get:
      operationId: listTrades
      summary: List trades
      description: List trades for a given account for the current trading day.
      tags:
        - Trades
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list trades for.
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            maximum: 2000
            default: 25
            description: Number of trades to return per page.
        - in: query
          name: page_token
          schema:
            type: string
            description: Cursor for the page to return.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trade'
                  next_page_token:
                    type: string
                    description: Cursor for the next page of results.
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/positions/{symbol}:
    get:
      operationId: getPosition
      summary: Get position
      description: Get current position for a given account for a given symbol.
      tags:
        - Positions
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to get the position for.
        - in: path
          name: symbol
          required: true
          schema:
            $ref: '#/components/schemas/Symbol'
            description: Symbol to get position for.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/positions:
    get:
      operationId: listPositions
      summary: List positions
      description: List current positions for a given account.
      tags:
        - Positions
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list positions for.
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            maximum: 2000
            default: 25
            description: Number of positions to return per page.
        - in: query
          name: page_token
          schema:
            type: string
            description: Cursor for the page to return.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Position'
                  next_page_token:
                    type: string
                    description: Cursor for the next page of results.
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/locate-orders:
    post:
      operationId: createLocateOrder
      summary: Create locate order
      description: Create locate order to borrow inventory for short-selling.
      tags:
        - Locates
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to create the locate order for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                symbol:
                  $ref: '#/components/schemas/Symbol'
                quantity:
                  $ref: '#/components/schemas/Quantity'
                mpid:
                  type: string
                  minLength: 1
                  maxLength: 256
                  description: The market participant where the locate will be sent.
                reference_id:
                  $ref: '#/components/schemas/ReferenceId'
                  description: Your unique ID for this locate order.
                comments:
                  type: string
                  description: Any additional comments for the locate request.
              required:
                - symbol
                - quantity
                - mpid
                - reference_id
      responses:
        '200':
          description: Locate order successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocateOrder'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
    get:
      operationId: listLocateOrders
      summary: List locate orders
      description: List all locate orders
      tags:
        - Locates
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list locate orders for.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocateOrder'
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/locate-orders/{locate_order_id}:
    get:
      operationId: getLocateOrder
      summary: Get locate order
      description: Get locate order by its unique locate order ID.
      tags:
        - Locates
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to get the locate order for.
        - in: path
          name: locate_order_id
          required: true
          schema:
            $ref: '#/components/schemas/LocateOrderId'
            description: Locate order ID to get.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocateOrder'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
    patch:
      operationId: updateLocateOrder
      summary: Update locate order
      description: Accept or decline locate order that has been offered.
      tags:
        - Locates
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to update the locate order for.
        - in: path
          name: locate_order_id
          required: true
          schema:
            $ref: '#/components/schemas/LocateOrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accept:
                  type: boolean
                  description: Accept or decline the locate order.
              required:
                - accept
      responses:
        '200':
          description: Locate accepted or declined successfully.
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/easy-borrows:
    get:
      operationId: listEasyBorrows
      summary: List easy borrows
      description: List all current easy-to-borrow stock symbols. This list changes dynamically daily.
      tags:
        - Rates
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to list easy borrows for.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Symbol'
                required:
                  - data
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts/{account_id}/inventories/{symbol}:
    get:
      operationId: getInventory
      summary: Get inventory
      description: Get located inventory for a symbol.
      tags:
        - Inventories
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
            description: The account ID or account number to get the inventory for.
        - in: path
          name: symbol
          required: true
          schema:
            $ref: '#/components/schemas/Symbol'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocateInventory'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /entities:
    get:
      operationId: listEntities
      summary: List entities
      description: List all available entities.
      tags:
        - Entities
      responses:
        '200':
          description: A list of entities
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Entity'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /entities/{entity_id}:
    get:
      operationId: getEntity
      summary: Get entity
      description: Get an entity by its ID.
      tags:
        - Entities
      parameters:
        - name: entity_id
          in: path
          required: true
          description: The ID of the entity to get.
          schema:
            $ref: '#/components/schemas/EntityId'
      responses:
        '200':
          description: The entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        default:
          $ref: '#/components/responses/error'
      security:
        - BearerAuth: []
  /accounts:
    get:
      operationId: listAccounts
      summary: List accounts
      description: List all available accounts.
      tags:
        - Accounts
      responses:
        '200':
          description: A list of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/s

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clear-street/refs/heads/main/openapi/clear-street-studio-openapi.yml