Search instruments and manage saved screeners.
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:
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
FieldType:
type: string
description: The data type of a screener field value.
enum:
- DECIMAL
- INTEGER
- STRING
- ANALYST_RATING
- DATE
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
ScreenerRow:
type: array
items:
$ref: '#/components/schemas/ScreenerColumn'
description: A single row of screener columns for one instrument.
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.'
SortDirection:
type: string
description: Sort direction sorted results
enum:
- ASC
- DESC
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
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
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
OperatorArg:
type: string
description: Argument that modifies operator behavior.
enum:
- LEFT_INCLUSIVE
- RIGHT_INCLUSIVE
- LEFT_EXCLUSIVE
- RIGHT_EXCLUSIVE
- CASE_INSENSITIVE
FilterOperator:
type: string
description: 'Filter operators supported by the screener.
Abbreviated and lowercase forms are accepted as serde aliases for backward
compatibility with earlier API revisions; the canonical wire form is the
SCREAMING_SNAKE_CASE rendering.'
enum:
- LESS_THAN
- LESS_OR_EQUAL
- GREATER_THAN
- GREATER_OR_EQUAL
- EQUAL
- BETWEEN
- NOT_BETWEEN
- ONE_OF
- REGEX
- BEGINS_WITH
- ENDS_WITH
- CONTAINS
- IS_NULL
- IS_NOT_NULL
SortSpec:
type: object
description: A sort specification pairing a field with a direction.
required:
- field
properties:
direction:
$ref: '#/components/schemas/SortDirection'
description: Sort direction (defaults to DESC).
field:
$ref: '#/components/schemas/FieldRef'
description: The field to sort by.
example:
direction: DESC
field:
name: market_cap
ScreenerEntryList:
type: array
items:
$ref: '#/components/schemas/ScreenerEntry'
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
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
- 'null'
items:
$ref: '#/components/schemas/SortSpec'
updated_at:
type: string
format: date-time
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
ModifierOp:
type: string
description: Modifier operation applied to a variable.
enum:
- ADD
- SUBTRACT
BaseResponse:
type: object
required:
- metadata
properties:
error:
oneOf:
- oneOf:
- type: 'null'
- $ref: '#/components/schemas/ApiError'
description: Structured error details when the request is unsuccessful.
metadata:
$ref: '#/components/schemas/ResponseMetadata'
description: Response metadata, including the reques
# --- 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