Clear Street Screener API

openapi: 3.2.0
info:
  title: Clear Street Trading Screener API
  description: 'A unified, secure, and high-performance RESTful API for all client interactions with the Active trading platform.

    This specification provides a single source of truth for the API surface, covering order management, trade execution, market data, and account services.


    ### Authentication

    All endpoints require authentication via a JWT Bearer token provided in the `Authorization` header.


    ### Response Structure

    All responses, both for success and error, adhere to a standard envelope structure:

    - `data`: Contains the response payload on success, or `null` on error.

    - `error`: Contains a structured error object on failure, or `null` on success.

    - `metadata`: Contains the `request_id` and pagination information.


    ### WebSockets

    Real-time market data is available via WebSocket connections, which are not formally described in this OpenAPI specification. The following operations are available:

    - `market-data-l1-subscribe`: To start receiving L1 market data updates for a set of symbols.

    - `market-data-l1-unsubscribe`: To stop receiving L1 market data updates.'
  contact:
    name: Clear Street API Support
    url: https://clearstreet.io/contact
    email: concierge@clearstreet.com
  license:
    name: Proprietary
    url: https://clearstreet.io/terms
  version: 2025-10-31
servers:
- url: https://api.clearstreet.com
  description: Clear Street API
- url: https://api-dev.clearstreet.com
  description: Clear Street Development API
- url: http://localhost:5001
  description: Clear Street Local API
security:
- BearerAuth: []
tags:
- name: Screener
  description: Search instruments and manage saved screeners.
paths:
  /v1/saved-screeners:
    get:
      tags:
      - Screener
      summary: Get Screeners
      description: 'List saved screener configurations.


        Returns all screener configurations for the authenticated user.'
      operationId: get_screeners
      responses:
        '200':
          description: List of saved screeners
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ScreenerEntryList'
                type: object
              examples:
                SavedScreenerList:
                  summary: List of saved screeners for the authenticated user
                  value:
                    data:
                    - created_at: 2026-03-20 14:30:00+00:00
                      filters:
                      - left:
                          name: market_cap
                        op:
                          name: GREATER_OR_EQUAL
                        right:
                        - value: 1000000000.0
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Tech Large Caps
                      sorts:
                      - direction: DESC
                        field:
                          name: market_cap
                      updated_at: 2026-03-20 14:30:00+00:00
                    - columns:
                      - name: symbol
                      - name: price
                      - name: volume
                      created_at: 2026-03-21 09:00:00+00:00
                      filters:
                      - left:
                          name: volume
                        op:
                          name: GREATER_OR_EQUAL
                        right:
                        - value: 10000000.0
                      id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      name: High Volume
                      updated_at: 2026-03-21 09:00:00+00:00
                    metadata:
                      request_id: 1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      tags:
      - Screener
      summary: Create Screener
      description: 'Create a saved screener configuration.


        Persists a screener configuration for the authenticated user.'
      operationId: create_screener
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScreenerRequest'
        required: true
      responses:
        '200':
          description: Screener created successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ScreenerEntry'
                type: object
              examples:
                SavedScreener:
                  summary: A saved screener with filters and sort
                  value:
                    data:
                      columns:
                      - name: symbol
                      - name: price
                      - name: market_cap
                      created_at: 2026-03-20 14:30:00+00:00
                      filters:
                      - left:
                          name: market_cap
                        op:
                          name: GREATER_OR_EQUAL
                        right:
                        - value: 1000000000.0
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Tech Large Caps
                      sorts:
                      - direction: DESC
                        field:
                          name: market_cap
                      updated_at: 2026-03-20 14:30:00+00:00
                    metadata:
                      request_id: 1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                MalformedPayload:
                  summary: Malformed JSON in request body
                  value:
                    error:
                      code: 400
                      message: 'Failed to parse the request body as JSON: trailing comma at line 3 column 1'
                    metadata:
                      request_id: a91ced80-b496-44af-a923-b8b8f1fbdc83
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/saved-screeners/{screener_id}:
    get:
      tags:
      - Screener
      summary: Get Screener By ID
      description: 'Get a saved screener configuration by ID.


        Returns a single screener configuration for the authenticated user.'
      operationId: get_screener_by_id
      parameters:
      - name: screener_id
        in: path
        description: Screener ID
        required: true
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Screener details
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ScreenerEntry'
                type: object
              examples:
                SavedScreener:
                  summary: A saved screener configuration
                  value:
                    data:
                      columns:
                      - name: symbol
                      - name: price
                      - name: market_cap
                      created_at: 2026-03-20 14:30:00+00:00
                      filters:
                      - left:
                          name: market_cap
                        op:
                          name: GREATER_OR_EQUAL
                        right:
                        - value: 1000000000.0
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Tech Large Caps
                      sorts:
                      - direction: DESC
                        field:
                          name: market_cap
                      updated_at: 2026-03-20 14:30:00+00:00
                    metadata:
                      request_id: 1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                InvalidScreenerId:
                  summary: Invalid screener_id path parameter
                  value:
                    error:
                      code: 400
                      message: 'Cannot parse `screener_id` with value `123`: UUID parsing failed: invalid length: expected length 32 for simple format, found 3'
                    metadata:
                      request_id: 1940e272-8ce1-41bf-ad3e-7e2a9fd9c4df
        '404':
          description: Screener not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                ScreenerNotFound:
                  summary: Screener does not exist
                  value:
                    error:
                      code: 404
                      message: Some requested entity was not found
                    metadata:
                      request_id: cb63a84c-6b39-4c37-bfdd-588b8256c7ea
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
      - Screener
      summary: Replace Screener
      description: 'Update a saved screener configuration.


        Replaces the screener configuration for the authenticated user.

        If `name` is null, the existing name is preserved.'
      operationId: replace_screener
      parameters:
      - name: screener_id
        in: path
        description: Screener ID
        required: true
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScreenerRequest'
        required: true
      responses:
        '200':
          description: Screener updated successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ScreenerEntry'
                type: object
              examples:
                UpdatedScreener:
                  summary: Screener updated successfully
                  value:
                    data:
                      columns:
                      - name: symbol
                      - name: price
                      - name: market_cap
                      created_at: 2026-04-23 13:37:04.041398+00:00
                      filters:
                      - left:
                          name: market_cap
                        op:
                          name: GREATER_OR_EQUAL
                        right:
                        - value: 1000000000.0
                      id: 69fcb40a-1812-4856-b2d3-97dec805efee
                      name: Tech Large Caps
                      sorts:
                      - direction: ASC
                        field:
                          name: market_cap
                      updated_at: 2026-04-23 13:37:21.860106+00:00
                    metadata:
                      request_id: 71ac58a8-9b12-49b9-8301-6239febe4e56
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                MalformedPayload:
                  summary: Malformed JSON in request body
                  value:
                    error:
                      code: 400
                      message: 'Failed to parse the request body as JSON: trailing comma at line 3 column 1'
                    metadata:
                      request_id: b8d191a9-0f76-4867-996e-4845ae01d864
        '404':
          description: Screener not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                ScreenerNotFound:
                  summary: Screener does not exist
                  value:
                    error:
                      code: 404
                      message: Some requested entity was not found
                    metadata:
                      request_id: 2cf7b8b2-f4c7-4db5-a617-b45324352fb7
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    delete:
      tags:
      - Screener
      summary: Delete Screener
      description: 'Delete a saved screener configuration.


        Deletes the screener configuration for the authenticated user.'
      operationId: delete_screener
      parameters:
      - name: screener_id
        in: path
        description: Screener ID
        required: true
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Screener deleted successfully
        '404':
          description: Screener not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                ScreenerNotFound:
                  summary: Screener does not exist
                  value:
                    error:
                      code: 404
                      message: Some requested entity was not found
                    metadata:
                      request_id: aafc54ec-939e-49a9-ab6e-bbabca005cb2
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/screener:
    post:
      tags:
      - Screener
      summary: Search Screener
      description: 'Search instruments using structured filters.


        Returns a columnar response where each row is an array of column objects.

        Each column contains a human-readable name, a field reference, an optional

        type hint (e.g. `CURR_USD`, `PERCENT`), and the value.


        Use `columns` to select which columns appear in each row.

        When omitted, the default field set is returned.'
      operationId: search_screener
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenerSearchRequest'
        required: true
      responses:
        '200':
          description: Screener results
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/ScreenerRowList'
                type: object
              examples:
                TwoResults:
                  summary: Filtered screener results with two instruments
                  value:
                    data:
                    - - field:
                          name: symbol
                        name: Symbol
                        value: AAPL
                      - field:
                          name: price
                        name: Price
                        type: CURR_USD
                        value: 175.05
                      - field:
                          name: market_cap
                        name: Market Cap
                        type: CURR_USD
                        value: 3500000000000
                      - field:
                          name: beta
                        name: Beta
                        value: 1.2
                      - field:
                          lookback: ONE_WEEK
                          name: change_pct
                        name: Change (1W)
                        type: PERCENT
                        value: 2.35
                      - field:
                          name: consensus_rating
                        name: Consensus Rating
                        value: STRONG_BUY
                      - field:
                          name: earnings_per_share
                          period: QUARTER
                        name: EPS (Q)
                        type: CURR_USD
                        value: 1.55
                    - - field:
                          name: symbol
                        name: Symbol
                        value: F
                      - field:
                          name: price
                        name: Price
                        type: CURR_USD
                        value: 12.5
                      - field:
                          name: market_cap
                        name: Market Cap
                        type: CURR_USD
                        value: 45000000000
                      - field:
                          name: beta
                        name: Beta
                        value: 1.5
                      - field:
                          lookback: ONE_WEEK
                          name: change_pct
                        name: Change (1W)
                        type: PERCENT
                        value: -0.85
                      - field:
                          name: consensus_rating
                        name: Consensus Rating
                        value: HOLD
                      - field:
                          name: earnings_per_share
                          period: QUARTER
                        name: EPS (Q)
                        type: CURR_USD
                        value: 0.23
                    metadata:
                      next_page_token: AAAAAAAAAAoAAAAAAAAAAg
                      request_id: abc-123
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Malformed request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                PayloadUnknownField:
                  summary: Unknown field in request payload
                  value:
                    error:
                      code: 422
                      message: 'Failed to deserialize the JSON body into the target type: unknown field `sort_by` at line 3 column 18'
                    metadata:
                      request_id: 69f02ce8-20e3-4bcd-a134-bb006eca5749
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    OperatorArg:
      type: string
      description: Argument that modifies operator behavior.
      enum:
      - LEFT_INCLUSIVE
      - RIGHT_INCLUSIVE
      - LEFT_EXCLUSIVE
      - RIGHT_EXCLUSIVE
      - CASE_INSENSITIVE
    ScreenerColumn:
      type: object
      description: A single column in the screener search response.
      required:
      - name
      - field
      - value
      properties:
        field:
          $ref: '#/components/schemas/FieldRef'
          description: Field reference (same shape as filter/sort field references)
        name:
          type: string
          description: Human-readable display name for this field
          example: Market Cap
        type:
          type:
          - string
          - 'null'
          description: 'Value format hint: "CURR_USD", "PERCENT", etc. Omitted when not applicable.

            When a null/undefined value is observed, it indicates it does not apply.'
        value:
          oneOf:
          - type: number
          - type: string
          - type: 'null'
      example:
        field:
          name: market_cap
          value_type: DECIMAL
        name: Market Cap
        type: CURR_USD
        value: 2890000000000.0
    Pagination:
      type: string
      format: byte
      description: Base64URL-encoded pagination token
    Modifier:
      type: object
      description: Arithmetic modifier applied to a variable value.
      required:
      - name
      - args
      properties:
        args:
          type: array
          items:
            oneOf:
            - type: number
            - type: string
        name:
          $ref: '#/components/schemas/ModifierOp'
          description: The modifier operation.
      example:
        args:
        - 30
        - DAY
        name: SUBTRACT
    ErrorDetails:
      type: array
      items:
        type: object
        additionalProperties: true
    ScreenerEntryList:
      type: array
      items:
        $ref: '#/components/schemas/ScreenerEntry'
    ScreenerRow:
      type: array
      items:
        $ref: '#/components/schemas/ScreenerColumn'
      description: A single row of screener columns for one instrument.
    SearchFilter:
      type: object
      description: 'A single filter condition.


        When `op` and `right` are both absent, the filter is "unenabled":

        it persists a `left` field reference without applying any predicate.

        Unenabled filters are skipped during search execution but still

        round-trip through save/load so callers can preserve draft state.'
      required:
      - left
      properties:
        left:
          $ref: '#/components/schemas/FieldRef'
          description: The field to filter on.
        op:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/FilterOpSpec'
            description: The operator and optional arguments. Omit together with `right` for an unenabled filter.
        right:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FilterValue'
          description: The value(s) to compare against. Omit together with `op` for an unenabled filter.
      example:
        left:
          name: market_cap
        op:
          name: GREATER_OR_EQUAL
        right:
        - value: 1000000000.0
    ModifierOp:
      type: string
      description: Modifier operation applied to a variable.
      enum:
      - ADD
      - SUBTRACT
    FilterOpSpec:
      type: object
      description: Operator specification with optional behavioral arguments.
      required:
      - name
      properties:
        args:
          type: array
          items:
            $ref: '#/components/schemas/OperatorArg'
          description: Optional arguments that modify operator behavior.
        name:
          $ref: '#/components/schemas/FilterOperator'
          description: The operator to apply.
      example:
        name: GREATER_OR_EQUAL
    ResponseMetadata:
      type: object
      description: 'Metadata for the response. This will always contain a request ID which can be used to identify

        the request to Clear Street for tracing, and optionally may include pagination data.'
      required:
      - request_id
      properties:
        next_page_token:
          oneOf:
          - type: 'null'
          - type: string
            format: byte
            description: Base64URL-encoded pagination token
          description: 'A token that can be used to retrieve the next page of results, if any.

            The token contains opaque pagination state.

            Filtering and sorting parameters must be provided with each request.'
        page_number:
          type:
          - integer
          - 'null'
          format: int32
          description: Pagination. Included if this was a GET (list) response
          example: '1'
          minimum: 0
        previous_page_token:
          oneOf:
          - type: 'null'
          - type: string
            format: byte
            description: Base64URL-encoded pagination token
          description: 'A token that can be used to retrieve the previous page of results, if any.

            The token contains opaque pagination state.

            Filtering and sorting parameters must be provided with each request.'
        request_id:
          type: string
          description: A unique ID for this request, generated upon ingestion of the request.
        total_items:
          type:
          - integer
          - 'null'
          format: int64
          description: Total number of items available (not just in this page).
          example: '42'
          minimum: 0
        total_pages:
          type:
          - integer
          - 'null'
          format: int32
          description: Total number of pages available.
          example: '5'
          minimum: 0
    ScreenerSearchRequest:
      allOf:
      - $ref: '#/components/schemas/PaginationParams'
      - type: object
        properties:
          columns:
            type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/FieldRef'
            description: Subset of fields to include in the response.
          filters:
            type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/SearchFilter'
            description: Filter conditions to apply.
          sort_case_sensitive:
            type:
            - boolean
            - 'null'
            description: 'Whether string sorts should be case-sensitive (default: false).'
          sorts:
            type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/SortSpec'
            description: Multi-field sort specifications.
      description: Request body for POST /screener.
      example:
        columns:
        - name: market_cap
        - name: price
        - name: volume
        filters:
        - left:
            name: market_cap
          op:
            name: GREATER_OR_EQUAL
          right:
          - value: 1000000000.0
        page_size: 25
        sorts:
        - direction: DESC
          field:
            name: market_cap
    SortDirection:
      type: string
      description: Sort direction sorted results
      enum:
      - ASC
      - DESC
    Variable:
      type: object
      description: A variable reference (field or built-in like `today`).
      required:
      - name
      properties:
        lookback:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/FieldLookback'
            description: Optional historical lookback window.
        modifier:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Modifier'
            description: Optional arithmetic modifier.
        name:
          type: string
          description: The variable name.
          example: today
        period:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/FieldPeriod'
            description: Optional reporting period.
      example:
        modifier:
          args:
          - 30
          - DAY
          name: SUBTRACT
        name: today
    FieldPeriod:
      type: string
      description: Reporting period for financial data fields.
      enum:
      - QUARTER
      - TRAILING_TWELVE_MONTHS
      - ANNUAL
    FieldLookback:
      type: string
      description: Historical lookback window for price/change fields.
      enum:
      - ONE_DAY
      - ONE_WEEK
      - ONE_MONTH
      - THREE_MONTHS
      - SIX_MONTHS
      - YEAR_TO_DATE
      - ONE_YEAR
    CreateScreenerRequest:
      type: object
      description: Request body for creating or updating a saved screener configuration
      properties:
        columns:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FieldRef'
          description: Structured field references to include when running this screener
        filters:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SearchFilter'
          description: Structured search filter criteria
        name:
          type:
          - string
          - 'null'
          description: The name for this screener configuration
        sorts:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SortSpec'
          description: Multi-field sort specifications
    ApiError:
      type: object
      description: A direct mapping of tonic::Status, for use in HTTP responses.
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: 'The error code is used to identify the nature of the error. It corresponds

            to an HTTP status code.'
          example: 400
          minimum: 0
        details:
          $ref: '#/components/schemas/ErrorDetails'
          description: 'Additional error details, if any. This can include structured information

            such as field violations or error metadata.'
        message:
          type: string
          description: A human-readable message providing more details about the error.
          example: Order quantity must be greater than zero
    FilterValue:
      type: object
      description: 'A filter value: either a literal or a variable reference.'
      properties:
        value:
          oneOf:
          - type: number
          - type: string
          - type: 'null'
        variable:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Variable'
            description: A variable reference.
      example:
        value: 1000000000.0
    PaginationParams:
      type: object
      description: 'Pagination parameters for list endpoints


        **Important:** `page_token` contains both limit and offset. When `page_token` is provided,

        `page_size` is ignored. Only use `page_size` for the first request.'
      properties:
        page_size:
          type:
          - integer
          - 'null'
          description: The number of items to return per page (only used when page_token is not provided)
          minimum: 0
        page_token:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Pagination'
            description: 'Token for retrieving the next page of results. Contains encoded pagination state (limit + offset).

              When provided, page_size is ignored.'
    ScreenerRowList:
      type: array
      items:
        $ref: '#/components/schemas/ScreenerRow'
    ScreenerEntry:
      type: object
      description: A saved screener configuration entry
      required:
      - id
      - name
      - filters
      - created_at
      - updated_at
      properties:
        columns:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FieldRef'
          description: Field references included when running this screener.
        created_at:
          type: string
          format: date-time
        filters:
          type: array
          items:
            $ref: '#/components/schemas/SearchFilter'
        id:
          type: string
          format: uuid
        name:
          type: string
        sorts:
          type:
          - array
          - 'nu

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