Clear Street Uploads API

openapi: 3.2.0
info:
  version: 0.0.3
  title: Clear Street Uploads API
  contact:
    name: API Support
    email: eng@clearstreet.io
    url: https://clear-street.github.io/docs
  x-logo:
    url: https://clear-street.github.io/docs/assets/logo.png
    backgroundColor: '#FFFFFF'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: This is a beta version of Clear Street's public API.
servers:
- url: //api.clearstreet.io/v1
  description: Production server
- url: //api.sandbox.clearstreet.io/v1
  description: Sandbox server
tags:
- name: Uploads
  description: Upload endpoints allow you to upload a `CSV` file that contain trades, in the same format as our trade-file specification. You may prefer to use a file-upload if you have a extremely large number of trades (> 10000), or if you have dependency on legacy systems that deal with `CSV` files. We recommend using trade endpoints when possible, especially for real-time trade reporting.
paths:
  /uploads/insert:
    post:
      tags:
      - Uploads
      summary: Create Insert Upload
      description: 'Upload the provided CSV file for processing asynchronously. Your file will be uploaded to our servers, and then subsequently processed.


        The columns for a CSV file should match the JSON path dot-notation of the fields available in the insert trades endpoint. For example, the column `side.direction` would be the column header to set the direction of a trade, and the column `instrument.ticker` would set the trade''s instrument ticker, etc.


        Our trade-file specification has more details. You can also download an example file.'
      operationId: uploads_insert_create
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The file to upload. Must have a *.csv extension.
                  format: binary
              required:
              - file
  /uploads/cancel:
    post:
      tags:
      - Uploads
      summary: Create Cancel Upload
      description: 'Upload the provided CSV file for processing cancels asynchronously.


        Example column headers with associated example values:


        account100001


        trade_id12343


        by_client_idfalse'
      operationId: uploads_cancel_create
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The file to upload. Must have a *.csv extension.
                  format: binary
              required:
              - file
  /uploads/{upload_id}:
    get:
      tags:
      - Uploads
      summary: Get Upload By ID
      description: Get an existing upload. Use this endpoint when you want to the know the status of a previously created upload.
      operationId: uploads_get_by_id
      parameters:
      - in: path
        name: upload_id
        required: true
        description: upload_id that identifies a previously created upload
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ErrorBase:
      type: object
      properties:
        message: null
        type: string
        description: Error details, if any
      example:
        message: <error-details>
    Error:
      type: object
      allOf:
      - $ref: '#/components/schemas/ErrorBase'
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - internal
          - malformed_trade
          - too_many_trades
          - file_exists
          - empty_file
          - unsupported_file
          - upload_not_found
          - trade_already_canceled
          - missing_account_id
    UploadStatus:
      type: object
      allOf:
      - $ref: '#/components/schemas/Upload'
      description: Represents an upload's status
      required:
      - trades_processed
      - trades_skipped
      - status
      - completed
      properties:
        updated_at:
          type: integer
          description: Timestamp when the upload was last updated; milliseconds since unix epoch
        trades_processed:
          type: integer
          description: The number of trades processed from this upload
        trades_skipped:
          type: integer
          description: The number of trades skipped from this upload
        status:
          type: string
          description: The status of this upload
        completed:
          type: boolean
          description: True if this upload has finished processing
    Upload:
      type: object
      description: Represents an upload's details
      required:
      - created_at
      - upload_id
      - org_id
      - user_id
      - name
      - s3_key
      properties:
        created_at:
          type: integer
          description: Timestamp when the upload was created; milliseconds since unix epoch
        upload_id:
          type: string
          description: SHA256 hash of the trades you uploaded. This uniquely identifies your upload
          example: 3d4b424aa96e2751228ad4b78f8882073e5e29079047ad524a0ed719b57c42db
        org_id:
          type: integer
          format: int64
          description: The orgID of the user who created this upload
          example: 1
        user_id:
          type: integer
          format: int64
          description: The userID of the user who created this upload
          example: 1
        name:
          type: string
          description: Name of the upload; this will be the filename if the upload
        s3_key:
          type: string
          description: AWS S3 key