Clear Street API version API

openapi: 3.2.0
info:
  title: Clear Street Trading API version 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: API version
  description: Endpoints for API service metadata.
paths:
  /v1/version:
    get:
      tags:
      - API version
      summary: Get the API version.
      description: Returns the current version string for this API endpoint.
      operationId: get_version
      responses:
        '200':
          description: API version information
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/Version'
                type: object
              examples:
                CurrentVersion:
                  summary: Current API version
                  value:
                    data:
                      version: 2025-10-31
                    error: null
                    metadata:
                      request_id: 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    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
    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
    Version:
      type: object
      description: API version information
      required:
      - version
      properties:
        version:
          type: string
          description: API version string
    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 request ID and optional pagination info.
    ErrorDetails:
      type: array
      items:
        type: object
        additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT