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: "<b>This is a beta version of Clear Street's public API. This API is RESTful; it has resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP codes, authentication, and verbs.</b>\n\n# Environments\nClear Street operates two environments: sandbox and production. Each environment is completely isolated from the other. No data is ever shared. All activity in our sandbox environment has no actual impact; all accounts in our sandbox use canned data. We recommend testing in our sandbox environment first before moving to production.\n\nThe following are the base URLs for each environment. Each endpoint in this API must be prefixed with one of the following base URLs:\n\nSandbox base URL: `https://api.sandbox.clearstreet.io/v1`\n\nProduction base URL: `https://api.clearstreet.io/v1`\n\n# Authentication\nEnd-to-end security is provided through an SSL connection and an API-key that will be provided to users of our API.\n\nThe API-key provided to you will take the form a <a href=\"https://swagger.io/docs/specification/authentication/bearer-authentication\">bearer token</a>. Every request you make, therefore, must contain your API-key in the header of the request in the following form:\n\n<pre>Authorization: Bearer &lt;KEY&gt;</pre>\n\nWhere `<KEY>` is the API-key provided to you.\n\nHere's an example of constructing a request in Python:\n\n```python\nimport requests\n\n# change URL based on environment\nURL = \"https://api.sandbox.clearstreet.io/v1/trades\"\n\n# set provided API-key here\nheaders = {\n    'Content-Type': 'application/json',\n    'Authorization': 'Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXQiOjE1ODU2MTk2NDYsImV4cCI6MTU4NTYyMzI0NiwidWlkIjoyfQ.B6wdfKRro9JxPrhjn8QchPOfGFSWexfg_2EX0V_tkdA'\n}\n\n# construct your message\npayload = [{\n    \"type\": \"allocation_trade\",\n    \"timestamp\": 1556544618,\n    \"client_trade_id\": \"042919-1a\",\n    \"date\": 20190304,\n    \"account_id\": 100016,\n    \"mic\": \"XNAS\",\n    \"exec_mpid\": \"CSMM\",\n    \"capacity\": \"principal\",\n    \"quantity\": \"100\",\n    \"price\": \"140.00\",\n    \"instrument\": {\n        \"identifier\": \"ATRA\",\n        \"identifier_type\": \"ticker\",\n        \"currency\": \"USD\",\n        \"country\": \"USA\"\n    },\n    \"side\": {\n        \"direction\": \"buy\"\n    },\n    \"target_account_id\": 100021\n}]\n\n# send request\nrequests.post(url=URL, headers=headers, json=payload)\n```\n"
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 <b>[trade-file specification](https://github.com/clear-street/docs/blob/master/trade_file.md)</b>. 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 <b><a href="#tag/Trades">trade endpoints</a></b> 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 <b><a href="#operation/trades_insert">insert trades endpoint</a></b>. 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 <b>[trade-file specification](https://github.com/clear-street/docs/blob/master/trade_file.md)</b> has more details. You can also <b><a href="examples/trades.csv">download an example file</a></b>.

        '
      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&#58;

        <table>

        <tr><th>account</th><td>100001</td></tr>

        <tr><th>trade_id</th><td>12343</td></tr>

        <tr><th>by_client_id</th><td>false</td></tr>

        </table>

        '
      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:
    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
    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
    ErrorBase:
      type: object
      properties:
        message: null
        type: string
        description: Error details, if any
      example:
        message: <error-details>
    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