public-api.yaml

openapi: "3.0.0"

info:
  version: "1.0.0"
  title: "MOSTLY AI"
  description: |
    API access to your MOSTLY AI platform.

    ### Authentication

    To access the endpoints of this API, you must provide a valid API key. You can obtain an API key by signing up on our platform. Once you have your API key, you must include it in all your requests by adding it to the header:

    ```
    X-MOSTLY-API-KEY: your-api-key-here
    ```

    Please replace `your-api-key-here` with your actual API key. If your API key is missing or invalid, you will receive a `401 Unauthorized` response.

tags:
  - name: "Connectors"
    description: "Integration with external data sources and data destinations"
  - name: "Generators"
    description: "Training a generator based on some source data"
  - name: "Source Tables"
    description: "A source data table"
  - name: "Source Columns"
    description: "A source data column"
  - name: "Source Foreign Keys"
    description: "A source data foreign key"
  - name: "Generator Training"
    description: "The training of a generator"
  - name: "Synthetic Probes"
    description: "Generate a synthetic probe based on a trained generator"
  - name: "Synthetic Datasets"
    description: "Generate a synthetic dataset based on a trained generator"
  - name: "Synthetic Tables"
    description: "A synthetic data table"
  - name: "Synthetic Generation"
    description: "The generation of a synthetic dataset"
  - name: "Assistant"
    description: "An AI-powered Assistant with a Python compute environment"
  - name: "Users"
    description: "User management"
  - name: "Likes"
    description: "Like, unlike or count likes on resources"
  - name: "Organizations"
    description: "Organization management"

paths:

  # CONNECTORS
  /connectors:
    get:
      summary: "List connectors"
      description: |
        Paginate through all connectors that the user has access to.
        Only connectors, that are independent of a table, will be returned.
      operationId: "listConnectors"
      tags: [ "Connectors" ]
      parameters:
        - $ref: "#/components/parameters/pageOffset"
        - $ref: "#/components/parameters/pageLimit"
        - $ref: "#/components/parameters/filterBySearchTerm"
        - $ref: "#/components/parameters/filterByConnectorAccessType"
        - $ref: "#/components/parameters/filterByOwnerId"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  totalCount:
                    $ref: "#/components/schemas/PaginatedTotalCount"
                  results:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/ConnectorListItem"
    post:
      summary: "Create connector"
      description: |
        Create a connector, and optionally validate the connection before saving.

        If validation fails, a 400 status with an error message will be returned.
      operationId: "createConnector"
      tags: [ "Connectors" ]
      parameters:
        - $ref: "#/components/parameters/testConnection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConnectorConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
        "400":
          $ref: "#/components/responses/BadRequest"
  /connectors/{id}:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    get:
      summary: "Retrieve connector"
      operationId: "getConnector"
      tags: [ "Connectors" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
    patch:
      summary: "Update connector"
      description: |
        Update a connector, and optionally validate the connection before saving.

        If validation fails, a 400 status with an error message will be returned.
      operationId: "patchConnector"
      tags: [ "Connectors" ]
      parameters:
        - $ref: "#/components/parameters/testConnection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConnectorPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
        "400":
          $ref: "#/components/responses/BadRequest"
    delete:
      summary: "Delete connector"
      operationId: "deleteConnector"
      tags: [ "Connectors" ]
      responses:
        "200":
          description: "OK"
        "400":
          $ref: "#/components/responses/BadRequest"
  /connectors/{id}/config:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    get:
      summary: "Retrieve configurable Connector properties as JSON"
      operationId: "getConnectorConfig"
      tags: [ "Connectors" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorConfig"
  /connectors/{id}/locations:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    get:
      summary: "List connector locations"
      description: |
        List the available databases, schemas, tables or folders for a connector.
        For storage connectors, this returns list of folders and files at root, respectively at `prefix` level.
        For DB connectors, this returns list of schemas (or databases for DBs without schema), respectively list of tables if `prefix` is provided.

        The formats of the locations are:

        - Cloud storage:
            - `AZURE_STORAGE`: `container/path`
            - `GOOGLE_CLOUD_STORAGE`: `bucket/path`
            - `S3_STORAGE`: `bucket/path`
        - Database:
            - `BIGQUERY`: `dataset.table`
            - `DATABRICKS`: `schema.table`
            - `HIVE`: `database.table`
            - `MARIADB`: `database.table`
            - `MSSQL`: `schema.table`
            - `MYSQL`: `database.table`
            - `ORACLE`: `schema.table`
            - `POSTGRES`: `schema.table`
            - `SNOWFLAKE`: `schema.table`
      operationId: "listConnectorLocations"
      tags: [ "Connectors" ]
      parameters:
        - name: "prefix"
          description: "The prefix to filter the results by."
          in: "query"
          schema:
            type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "string"
  /connectors/{id}/schema:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    get:
      summary: "Get connector table schema"
      description: |
        List the available columns, as well as their data type for a connector table.
      operationId: "getConnectorTableSchema"
      tags: [ "Connectors" ]
      parameters:
        - name: "location"
          description: "Specifies the target within the connector from which to retrieve the schema. The format of this parameter varies by connector type."
          in: "query"
          schema:
            type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "object"
                  properties:
                    name:
                      description: "The name of the column."
                      type: "string"
                    originalDataType:
                      description: "The original vendor-specific data type of the column."
                      type: "string"
                    defaultModelEncodingType:
                      $ref: "#/components/schemas/ModelEncodingType"
  /connectors/{id}/transfer:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    put:
      summary: |
        Transfer ownership of the resource either to an organization where the current user has at least CONTRIBUTOR permissions, or to the current user themselves.
        Requires the current user to have resource permission level `ADMIN`.
      operationId: "transferOwnershipConnector"
      tags: [ "Connectors" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferOwnershipConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
  /connectors/{id}/visibility:
    parameters:
      - $ref: "#/components/parameters/connectorIdPath"
    put:
      summary: "Set connector visibility. Requires the current user to have resource permission level `ADMIN`."
      operationId: "setConnectorVisibility"
      tags: [ "Connectors" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetVisibilityConfig"
      responses:
        "200":
          description: "OK"

  # GENERATORS
  /generators:
    get:
      summary: "List generators"
      description: "Paginate through all generators that the user has access to."
      operationId: "listGenerators"
      tags: [ "Generators" ]
      parameters:
        - $ref: "#/components/parameters/pageOffset"
        - $ref: "#/components/parameters/pageLimit"
        - $ref: "#/components/parameters/filterByProgressStatus"
        - $ref: "#/components/parameters/filterBySearchTerm"
        - $ref: "#/components/parameters/filterByOwnerId"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                properties:
                  totalCount:
                    $ref: "#/components/schemas/PaginatedTotalCount"
                  results:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/GeneratorListItem"
    post:
      summary: "Create generator"
      description: "Create a generator."
      operationId: "createGenerator"
      tags: [ "Generators" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeneratorConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
        "400":
          $ref: "#/components/responses/BadRequest"
  /generators/{id}:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    get:
      summary: "Retrieve generator"
      operationId: "getGenerator"
      tags: [ "Generators" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
    patch:
      summary: "Update generator"
      operationId: "patchGenerator"
      tags: [ "Generators" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeneratorPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
    delete:
      summary: "Delete generator"
      operationId: "deleteGenerator"
      tags: [ "Generators" ]
      responses:
        "200":
          description: "OK"
        "400":
          $ref: "#/components/responses/BadRequest"
  /generators/{id}/like:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Like a generator"
      description: "Like the provided generator."
      operationId: "likeGenerator"
      tags: [ "Likes" ]
      responses:
        "200":
          description: "OK"
    delete:
      summary: "Unlike a generator"
      description: "Unlike the provided generator."
      operationId: "unLikeGenerator"
      tags: [ "Likes" ]
      responses:
        "200":
          description: "OK"
  /generators/{id}/config:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    get:
      summary: "Retrieve configurable Generator properties as JSON"
      operationId: "getGeneratorConfig"
      tags: [ "Generators" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratorConfig"
  /generators/{id}/clone:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Clone generator"
      description: |
        Create a new generator, re-using existing data and model configurations. By setting trainingStatus 
        to CONTINUE, the model weights are copied as well, and training will continue from there. Note, that
        in that case, only the training parameters (maxSampleSize, maxEpochs, batchSize, compute, etc.) of 
        the model configuration can still be modified. Other configurations, like columns, model, and 
        valueProtection cannot be changed anymore, as these would break compatibility with the existing model 
        weights.
      operationId: "cloneGenerator"
      tags: [ "Generators" ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeneratorCloneConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
        "400":
          $ref: "#/components/responses/BadRequest"
  /generators/{id}/export-to-file:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    get:
      summary: "Export generator as a file"
      description: |
        Export the generator as a self-contained single file, that can then be imported as a fully functional
        generator on a MOSTLY AI server.
      operationId: "exportGeneratorToFile"
      tags: [ "Generators" ]
      responses:
        "200":
          description: "OK"
          content:
            application/zip:
              schema:
                type: "string"
                format: "binary"
  /generators/import-from-file:
    post:
      summary: "Import generator from a file"
      description: |
        Import a generator from a self-contained single file, that was previously exported from a MOSTLY AI server. Generators will be imported as private.
      operationId: "importGeneratorFromFile"
      tags: [ "Generators" ]
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/GeneratorImportFromFileConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
  /generators/{id}/tables:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Add table to generator"
      operationId: "addSourceTable"
      tags: [ "Source Tables" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceTableAddConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceTable"
  /generators/{id}/tables/upload:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Add table to generator by uploading a data file"
      operationId: "uploadSourceTable"
      tags: [ "Source Tables" ]
      requestBody:
        # Moved the requestBody definition inline since the OpenAPI Generator
        # generates a Kotlin object lacking the @RequestPart or @RequestParam annotations.
        # This absence may lead to 415 error in Spring due to mapping issues.
        content:
          multipart/form-data:
            schema:
              type: "object"
              properties:
                file:
                  type: "string"
                  format: "binary"
                name:
                  $ref: "#/components/schemas/SourceTableName"
                primaryKey:
                  $ref: "#/components/schemas/SourceTablePrimaryKey"
                tabularModelConfiguration:
                  $ref: "#/components/schemas/ModelConfiguration"
                languageModelConfiguration:
                  $ref: "#/components/schemas/ModelConfiguration"
              required:
                - file
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceTable"
  /generators/{id}/tables/{tableId}:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
    get:
      summary: "Retrieve table from generator"
      operationId: "getSourceTable"
      tags: [ "Source Tables" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceTable"
    patch:
      summary: "Update table in generator"
      description: "Update a source table, and optionally provide model configurations."
      operationId: "patchSourceTable"
      tags: [ "Source Tables" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceTablePatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceTable"
    delete:
      summary: "Delete table from generator"
      operationId: "deleteSourceTable"
      tags: [ "Source Tables" ]
      responses:
        "200":
          description: "OK"
  /generators/{id}/tables/{tableId}/report:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
    get:
      summary: "Retrieve model report"
      operationId: "getModelReport"
      tags: [ "Source Tables" ]
      parameters:
        - $ref: "#/components/parameters/modelType"
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            text/html:
              schema:
                type: "string"
  /generators/{id}/tables/{tableId}/samples:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
    get:
      summary: "Retrieve 10 random model samples as JSON array"
      operationId: "getModelSamples"
      tags: [ "Source Tables" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Samples"
  /generators/{id}/tables/{tableId}/columns/{columnId}:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
      - $ref: "#/components/parameters/sourceColumnIdPath"
    get:
      summary: "Retrieve column from table"
      operationId: "getSourceColumn"
      tags: [ "Source Columns" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceColumn"
    patch:
      summary: "Update column in table"
      operationId: "patchSourceColumn"
      tags: [ "Source Columns" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceColumnPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceColumn"
  /generators/{id}/tables/{tableId}/foreign-keys:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
    post:
      summary: Create foreign key
      operationId: createSourceForeignKey
      tags: [ "Source Foreign Keys" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceForeignKeyConfig"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceForeignKey"

  /generators/{id}/tables/{tableId}/foreign-keys/{foreignKeyId}:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/sourceTableIdPath"
      - $ref: "#/components/parameters/sourceForeignKeyIdPath"
    patch:
      summary: Update foreign key
      operationId: patchSourceForeignKey
      tags: [ "Source Foreign Keys" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceForeignKeyPatchConfig"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceForeignKey"
    delete:
      summary: Delete foreign key
      operationId: deleteSourceForeignKey
      tags: [ "Source Foreign Keys" ]
      responses:
        200:
          description: OK
  /generators/{id}/training:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    get:
      summary: "Retrieve training progress"
      operationId: "getTrainingProgress"
      tags: [ "Generator Training" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobProgress"
  /generators/{id}/training/start:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Start training"
      operationId: "startTraining"
      tags: [ "Generator Training" ]
      responses:
        "200":
          description: "OK"
  /generators/{id}/training/steps/{stepId}/stop:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
      - $ref: "#/components/parameters/stepIdPath"
    post:
      summary: "Stop training"
      operationId: "stopTraining"
      tags: [ "Generator Training" ]
      responses:
        "200":
          description: "OK"
  /generators/{id}/training/cancel:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    post:
      summary: "Cancel training"
      operationId: "cancelTraining"
      tags: [ "Generator Training" ]
      responses:
        "200":
          description: "OK"
  /generators/{id}/training/logs:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    get:
      summary: "Download training logs"
      operationId: "downloadTrainingLogs"
      tags: [ "Generator Training" ]
      parameters:
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            application/zip:
              schema:
                type: "string"
                format: "binary"
  /generators/{id}/transfer:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    put:
      summary: |
        Transfer ownership of the resource either to an organization where the current user has at least CONTRIBUTOR permissions, or to the current user themselves.
        Requires the current user to have resource permission level `ADMIN`.
      operationId: "transferOwnershipGenerator"
      tags: [ "Generators" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferOwnershipConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generator"
  /generators/{id}/visibility:
    parameters:
      - $ref: "#/components/parameters/generatorIdPath"
    put:
      summary: "Set generator visibility. Requires the current user to have resource permission level `ADMIN`."
      operationId: "setGeneratorVisibility"
      tags: [ "Generators" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetVisibilityConfig"
      responses:
        "200":
          description: "OK"

  # SYNTHETIC DATASETS
  /synthetic-datasets:
    get:
      summary: "List synthetic datasets"
      operationId: "listSyntheticDatasets"
      tags: [ "Synthetic Datasets" ]
      parameters:
        - $ref: "#/components/parameters/pageOffset"
        - $ref: "#/components/parameters/pageLimit"
        - $ref: "#/components/parameters/filterByProgressStatus"
        - $ref: "#/components/parameters/filterBySearchTerm"
        - $ref: "#/components/parameters/filterByOwnerId"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                properties:
                  totalCount:
                    $ref: "#/components/schemas/PaginatedTotalCount"
                  results:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/SyntheticDatasetListItem"
    post:
      summary: "Create synthetic dataset"
      operationId: "createSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyntheticDatasetConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticDataset"
  /synthetic-datasets/{id}:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    get:
      summary: "Retrieve synthetic dataset"
      operationId: "getSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticDataset"
    patch:
      summary: "Update synthetic dataset"
      operationId: "patchSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyntheticDatasetPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticDataset"
    delete:
      summary: "Delete synthetic dataset"
      operationId: "deleteSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      responses:
        "200":
          description: "OK"
  /synthetic-datasets/{id}/like:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    post:
      summary: "Like a synthetic dataset"
      description: "Like the provided synthetic dataset."
      operationId: "likeSyntheticDataset"
      tags: [ "Likes" ]
      responses:
        "200":
          description: "OK"
    delete:
      summary: "Unlike a synthetic dataset"
      description: "Unlike the provided synthetic dataset."
      operationId: "unLikeSyntheticDataset"
      tags: [ "Likes" ]
      responses:
        "200":
          description: "OK"
  /synthetic-datasets/{id}/config:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    get:
      summary: "Retrieve configurable Synthetic Dataset properties as JSON"
      operationId: "getSyntheticDatasetConfig"
      tags: [ "Synthetic Datasets" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticDatasetConfig"
  /synthetic-datasets/{id}/tables/{tableId}:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
      - $ref: "#/components/parameters/syntheticTableIdPath"
    get:
      summary: "Retrieve table from synthetic dataset"
      operationId: "getSyntheticTable"
      tags: [ "Synthetic Tables" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticTable"
    patch:
      summary: "Update table in synthetic dataset"
      operationId: "patchSyntheticTable"
      tags: [ "Synthetic Tables" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyntheticTablePatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticTable"
  /synthetic-datasets/{id}/tables/{tableId}/upload:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
      - $ref: "#/components/parameters/syntheticTableIdPath"
    post:
      summary: "Add sample seed data to synthetic dataset by uploading a data file"
      operationId: "uploadSampleSeed"
      tags: [ "Synthetic Tables" ]
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: "object"
              properties:
                file:
                  type: "string"
                  format: "binary"
              required:
                - "file"
      responses:
        "200":
          description: "OK"
  /synthetic-datasets/{id}/tables/{tableId}/report:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
      - $ref: "#/components/parameters/syntheticTableIdPath"
      - $ref: "#/components/parameters/reportType"
    get:
      summary: "Retrieve synthetic data report"
      operationId: "getDataReport"
      tags: [ "Synthetic Tables" ]
      parameters:
        - $ref: "#/components/parameters/shortLivedFileToken"
        - $ref: "#/components/parameters/modelType"
      responses:
        "200":
          description: "OK"
          content:
            text/html:
              schema:
                type: "string"
  /synthetic-datasets/{id}/tables/{tableId}/samples:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
      - $ref: "#/components/parameters/syntheticTableIdPath"
    get:
      summary: "Retrieve 10 random data samples as JSON"
      operationId: "getDataSamples"
      tags: [ "Synthetic Tables" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /synthetic-datasets/{id}/generation:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    get:
      summary: "Retrieve generation progress"
      operationId: "getGenerationProgress"
      tags: [ "Synthetic Generation" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobProgress"
  /synthetic-datasets/{id}/generation/start:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    post:
      summary: "Start generation"
      operationId: "startGeneration"
      tags: [ "Synthetic Generation" ]
      responses:
        "200":
          description: "OK"
  /synthetic-datasets/{id}/generation/cancel:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    post:
      summary: "Cancel generation"
      operationId: "cancelGeneration"
      tags: [ "Synthetic Generation" ]
      responses:
        "200":
          description: "OK"
  /synthetic-datasets/{id}/generation/logs:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    get:
      summary: "Download generation logs"
      operationId: "downloadGenerationLogs"
      tags: [ "Synthetic Generation" ]
      parameters:
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            application/zip:
              schema:
                type: "string"
                format: "binary"
  /synthetic-datasets/{id}/download:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    get:
      summary: "Download synthetic dataset"
      operationId: "downloadSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      parameters:
        - name: "format"
          in: "query"
          schema:
            $ref: "#/components/schemas/SyntheticDatasetFormat"
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            application/zip:
              schema:
                type: "string"
                format: "binary"
  /synthetic-datasets/{id}/transfer:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    put:
      summary: |
        Transfer ownership of the resource either to an organization where the current user has at least CONTRIBUTOR permissions, or to the current user themselves.
        Requires the current user to have resource permission level `ADMIN`.
      operationId: "transferOwnershipSyntheticDataset"
      tags: [ "Synthetic Datasets" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferOwnershipConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyntheticDataset"
  /synthetic-datasets/{id}/visibility:
    parameters:
      - $ref: "#/components/parameters/syntheticDatasetIdPath"
    put:
      summary: "Set synthetic dataset visibility. Requires the current user to have resource permission level `ADMIN`."
      operationId: "setSyntheticDatasetVisibility"
      tags: [ "Synthetic Datasets" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetVisibilityConfig"
      responses:
        "200":
          description: "OK"

  /synthetic-probes:
    post:
      summary: "Create synthetic probe"
      operationId: "createSyntheticProbe"
      tags: [ "Synthetic Probes" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyntheticProbeConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                items:
                  $ref: "#/components/schemas/Probe"

  ## ASSISTANT
  /assistant/settings:
    get:
      summary: "Retrieve assistant settings. Only accessible for SuperAdmins."
      operationId: "getAssistantSettings"
      tags: [ "Assistant" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssistantSettings"
    put:
      summary: "Update assistant settings. Only accessible for SuperAdmins."
      operationId: "updateAssistantSettings"
      tags: [ "Assistant" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssistantSettings"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssistantSettings"

  /assistant/threads:
    get:
      summary: "List assistant threads"
      operationId: "listAssistantThreads"
      tags: [ "Assistant" ]
      parameters:
        - $ref: "#/components/parameters/pageOffset"
        - $ref: "#/components/parameters/pageLimit"
        - $ref: "#/components/parameters/filterBySearchTerm"
        - $ref: "#/components/parameters/filterByOwnerId"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                properties:
                  totalCount:
                    $ref: "#/components/schemas/PaginatedTotalCount"
                  results:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/AssistantThreadListItem"
    post:
      summary: "Create assistant thread"
      operationId: "createAssistantThread"
      tags: [ "Assistant" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssistantThreadConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssistantThread"

  /assistant/threads/{id}:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    get:
      summary: "Retrieve assistant thread"
      operationId: "getAssistantThread"
      tags: [ "Assistant" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssistantThread"
    patch:
      summary: "Update assistant thread"
      operationId: "patchAssistantThread"
      tags: [ "Assistant" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssistantThreadPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssistantThread"
    delete:
      summary: "Delete assistant thread"
      operationId: "deleteAssistantThread"
      tags: [ "Assistant" ]
      responses:
        "200":
          description: "OK"
  /assistant/threads/{id}/status:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    get:
      summary: "Get the session status of a thread"
      operationId: "getStatus"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    $ref: "#/components/schemas/AssistantThreadSessionStatus"
  /assistant/threads/{id}/export:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    get:
      summary: "Export the assistant thread"
      operationId: "exportThread"
      parameters:
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            application/zip:
              schema:
                type: "string"
                format: "binary"
  /assistant/threads/{id}/messages:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    post:
      summary: "Create a message"
      operationId: "createAssistantMessage"
      x-codegen-ignore: true
      tags: [ "Assistant" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssistantMessageConfig"
      responses:
        "200":
          description: |
            The newly created messages (excluding the user message)
            
            if stream=True then return stream of sever-sent events of type AssistantMessageDelta:
            
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'ok,', finishReason: None}
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'I', finishReason: None}
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'will,', finishReason: None}
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'write', finishReason: None}
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'some', finishReason: None}
              data: {id: 'xyz1', role: 'assistant', 'contentType': 'text', delta: 'python.', finishReason: None}

              data: {id: 'abc2', role: 'assistant', 'contentType': 'python', delta: 'r =', finishReason: None}
              data: {id: 'abc2', role: 'assistant', 'contentType': 'python', delta: 'r =', finishReason: None}
              data: {id: 'abc2', role: 'assistant', 'contentType': 'python', delta: 'r', finishReason: None}
              data: {id: 'abc2', role: 'assistant', 'contentType': 'python', delta: None, finishReason: 'tool_calls'}

              data: {id: 'def3', role: 'tool', 'contentType': 'text', delta: '3', finishReason: 'stop'}
            
              data: {id: 'ghi4', role: 'assistant', 'contentType': 'text', delta: 'The', finishReason: None}
              data: {id: 'ghi4', role: 'assistant', 'contentType': 'text', delta: 'answer', finishReason: None}
              data: {id: 'ghi4', role: 'assistant', 'contentType': 'text', delta: 'is', finishReason: None}
              data: {id: 'ghi4', role: 'assistant', 'contentType': 'text', delta: '3!', finishReason: 'stop'}

              data: [DONE]

          #            if stream=False then return array of AssistantMessages:
          #
          #              [
          #                {id: 'xyz1', role: 'assistant', 'contentType': 'text', content: 'ok, I will write some python.', finishReason: 'stop'},
          #                {id: 'abc2', role: 'assistant', 'contentType': 'python', content: 'r = sqrt(9)\nr', finishReason: 'tool_calls'},
          #                {id: 'def3', role: 'tool', 'contentType': 'text', content: '3', finishReason: 'stop'},
          #                {id: 'ghi4', role: 'assistant', 'contentType': 'text', content: 'The answer is 3!', finishReason: 'stop'},
          #              ]

          content:
            #            application/json:
            #              schema:
            #                type: "array"
            #                items:
            #                  - $ref: "#/components/schemas/AssistantMessage"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/AssistantMessageDelta"
  /assistant/threads/{id}/file:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    get:
      summary: "Fetch file in assistant thread"
      operationId: "fetchAssistantThreadFile"
      tags: [ "Assistant" ]
      parameters:
        - name: "filepath"
          in: "query"
          schema:
            type: "string"
          required: true
        - $ref: "#/components/parameters/shortLivedFileToken"
      responses:
        "200":
          description: "OK"
          content:
            application/octet-stream:
              schema:
                type: "string"
                format: "binary"
    put:
      summary: "Upload file to assistant thread"
      operationId: "uploadAssistantThreadFile"
      tags: [ "Assistant" ]
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: "object"
              properties:
                file:
                  type: "string"
                  format: "binary"
              required:
                - "file"
      responses:
        "200":
          description: "OK"
  /assistant/threads/{id}/interrupt:
    parameters:
      - $ref: "#/components/parameters/assistantThreadIdPath"
    post:
      summary: "Interrupt assistant thread streaming"
      operationId: "interruptAssistantThread"
      tags: [ "Assistant" ]
      responses:
        "200":
          description: "OK"

  # USERS
  /users/me/key:
    put:
      summary: "Generate API key for current user"
      operationId: "generateUserApiKey"
      tags: [ "Users" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  apiKey:
                    type: "string"
  /users/me:
    get:
      summary: "Retrieve current user info"
      operationId: "getCurrentUserInfo"
      tags: [ "Users" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrentUser"
    delete:
      summary: "Delete the current user"
      operationId: "deleteCurrentUser"
      tags: [ "Users" ]
      responses:
        "200":
          description: "OK"

  /users/me/settings:
    put:
      summary: "Update settings"
      operationId: "updateUserSettings"
      tags: [ "Users" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserSettingsUpdateConfig"
      responses:
        "200":
          description: "OK"

  /users/me/notifications:
    get:
      summary: "Retrieve notifications"
      description: "Retrieve notifications for the current user. All notifications are marked as read after retrieval."
      operationId: "getNotifications"
      tags: [ "Users" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/Notification"

  ## COMPUTES
  /computes:
    get:
      summary: "List the available computes"
      description: "List the available computes, sorted by order index. The first returned compute is the default compute."
      tags: [ "Computes" ]
      operationId: "listComputes"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/ComputeListItem"
    post:
      summary: "Create compute"
      operationId: "createCompute"
      description: |
        Create a compute. Only accessible for SuperAdmins.

        The structures of the config and secrets parameters depend on the compute type.

          ```yaml
          - type: KUBERNETES
            config:
              toleration: string
          - type: DATABRICKS
            config:
              instanceURL: string
              clusterID: string
            secrets:
              token: string
          ```
      tags: [ "Computes" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComputeConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Compute"
  /computes/{id}:
    parameters:
      - $ref: "#/components/parameters/computeIdPath"
    get:
      summary: "Retrieve compute"
      operationId: "getCompute"
      description: "Only accessible for SuperAdmins."
      tags: [ "Computes" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Compute"
    patch:
      summary: "Update compute"
      operationId: "patchCompute"
      description: |
        Update a compute. Only accessible for SuperAdmins.
        
        For the structure of the config and secrets, see the CREATE method.
      tags: [ "Computes" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComputePatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Compute"
    delete:
      summary: "Delete compute"
      operationId: "deleteCompute"
      description: "Only accessible for SuperAdmins."
      tags: [ "Computes" ]
      responses:
        "200":
          description: "OK"

  ## SYSTEM
  /about:
    get:
      summary: "Retrieve general info about service"
      operationId: "getAboutService"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AboutService"
  /usage-report/periods:
    get:
      summary: "Retrieve usage report by Periods"
      operationId: "getUsageReportByPeriods"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  usage:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/UsageReportPeriod"
  /usage-report/download:
    get:
      summary: "Download usage report as CSV"
      operationId: "downloadUsageReport"
      responses:
        "200":
          description: "OK"
          content:
            application/octet-stream:
              schema:
                type: "string"
                format: "binary"

  ## MODELS
  /models/{modelType}:
    parameters:
      - $ref: "#/components/parameters/modelTypePath"
    get:
      summary: "List the available models"
      tags: [ "Models" ]
      operationId: "listModels"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/ModelId"
  /models/LANGUAGE/config:
    get:
      summary: "Get current HuggingFace access key and list the available LANGUAGE models. Only accessible for SuperAdmins."
      tags: [ "Models" ]
      operationId: "getModelConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  models:
                    type: "array"
                    items:
                      type: "string"
                      description: "The model identifiers for the available models, without the LANGUAGE prefix."
                    example:
                      - "MOSTLY_AI/LSTM_not_pretrained"
                      - "mistralai/Mistral-7B-Instruct-v0.2"
                  huggingFaceToken:
                    type: "string"
                    description: "The access token for the HuggingFace model hub."
    put:
      summary: "Update the settings for available LANGUAGE models. Only accessible for SuperAdmins."
      tags: [ "Models" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                models:
                  type: "array"
                  items:
                    type: "string"
                    description: "The model identifiers for the available models, without the LANGUAGE prefix."
                  example:
                    - "MOSTLY_AI/LSTM_not_pretrained"
                    - "mistralai/Mistral-7B-Instruct-v0.2"
                huggingFaceToken:
                  type: "string"
                  description: "The access token for the HuggingFace model hub."
      responses:
        "200":
          description: "OK"

  # ORGANIZATIONS
  /organizations:
    get:
      summary: "List organizations"
      description: "Retrieve a list of all organizations. Any user can access this endpoint to get a list of organizations."
      operationId: "listOrganizations"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/pageOffset"
        - $ref: "#/components/parameters/pageLimit"
        - $ref: "#/components/parameters/filterBySearchTerm"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                properties:
                  totalCount:
                    $ref: "#/components/schemas/PaginatedTotalCount"
                  results:
                    type: "array"
                    items:
                      $ref: "#/components/schemas/OrganizationListItem"
    post:
      summary: "Create organization"
      description: "Create a new organization. Any user can create an organization."
      operationId: "createOrganization"
      tags: [ "Organizations" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrganizationConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
  /organizations/{id}:
    parameters:
      - $ref: "#/components/parameters/organizationIdPath"
    get:
      summary: "Retrieve organization"
      description: "Retrieve details of a specific organization. Accessible by all users. Public resources will be accessible to all users, while private resources will only be accessible to members of the organization."
      operationId: "getOrganization"
      tags: [ "Organizations" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
    patch:
      summary: "Update organization"
      description: "Update details of a specific organization. Only accessible by Organization Admins."
      operationId: "updateOrganization"
      tags: [ "Organizations" ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrganizationPatchConfig"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
    delete:
      summary: "Delete organization"
      description: "Delete a specific organization. Only accessible by Organization Admins."
      operationId: "deleteOrganization"
      tags: [ "Organizations" ]
      responses:
        "200":
          description: "OK"

  /organizations/{id}/members:
    parameters:
      - $ref: "#/components/parameters/organizationIdPath"
    get:
      summary: "List organization members"
      description: "Retrieve a list of all members of a specific organization. Accessible only by organization members."
      operationId: "listOrganizationMembers"
      tags: [ "Organizations" ]
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/OrganizationMember"

  /organizations/{id}/members/{userId}:
    delete:
      summary: "Remove user from organization. Organization Admins can remove any user, while members can only remove themselves."
      operationId: "removeUserFromOrganization"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/organizationIdPath"
        - $ref: "#/components/parameters/userIdPath"
      responses:
        "200":
          description: "OK"

  /organizations/{id}/members/{userId}/role:
    patch:
      summary: "Update user role"
      description: "Update the role of a user in the organization. Only accessible by Organization Admins."
      operationId: "updateMemberRole"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/organizationIdPath"
        - $ref: "#/components/parameters/userIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MemberRolePatchConfig"
      responses:
        200:
          description: "OK"

  /organizations/{id}/invite:
    get:
      summary: "Retrieve organization invite"
      description: "Retrieve an organization invite for users to join the organization."
      operationId: "retrieveOrganizationInvite"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/organizationIdPath"
        - $ref: "#/components/parameters/inviteToken"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationInvite"
    post:
      summary: "Generate invite link"
      description: "Generates new invite link to join the organization. Same link can be used by multiple users. Expires in 72 hours. Only accessible by Organization Admins."
      operationId: "generateInviteLink"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/organizationIdPath"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationInvite"

  /organizations/{id}/join:
    post:
      summary: "Accept invite"
      description: "Accept the invite to join the organization. Accessible by any user that has the invite-link."
      operationId: "acceptInvite"
      tags: [ "Organizations" ]
      parameters:
        - $ref: "#/components/parameters/organizationIdPath"
        - $ref: "#/components/parameters/inviteToken"
      responses:
        "200":
          description: "OK"

  /mostly-websocket:
    get:
      summary: WebSocket Connection
      description: Establish a WebSocket connection.
      responses:
        101:
          description: Switching Protocols
      x-websocket:
        summary: WebSocket Connection
        description: |
          This endpoint establishes a WebSocket connection using stomp protocol.
          Authorization is done via the `Authorization` connection header with value of Bearer token.
          After establishing the connection, the client should subscribe to the `/user/<user_id>/` topic to receive notifications.
          Received messages are in JSON format and have the following structure:
          ```json
            {"types":["GENERATOR_CREATED"],"resourceId":"81473b9d-4dd0-4f49-9a5b-72185349ce3f"}
          ```
          The `types` field is an array of events and is one of GENERATOR_CREATED, GENERATOR_STATUS_CHANGED, SYNTHETIC_DATASET_CREATED, SYNTHETIC_DATASET_STATUS_CHANGED, GENERATOR_MODEL_SAMPLES_CREATED, NOTIFICATIONS_UNREAD_COUNT.
          For the NOTIFICATIONS_UNREAD_COUNT event, the count of unread notifications is included in the message.
        protocol: websocket

components:
  securitySchemes:
    BearerAuth:
      type: "http"
      scheme: "bearer"
    ApiKeyAuth:
      type: "apiKey"
      in: "header"
      name: "X-MOSTLY-API-KEY"

  responses:

    BadRequest:
      description: "Bad Request"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              message:
                type: "string"
                description: "A human-readable error message"

  parameters:

    pageOffset:
      name: "offset"
      description: "Offset the entities in the response"
      in: "query"
      schema:
        type: "integer"
        default: 0
    pageLimit:
      name: "limit"
      description: "Limit the number of entities in the response"
      in: "query"
      schema:
        type: "integer"
        default: 50
        minimum: 1
        maximum: 1000
    connectorIdPath:
      name: "id"
      description: "The unique identifier of a connector."
      in: "path"
      required: true
      schema:
        type: "string"
    modelTypePath:
      name: "modelType"
      description: "Model type"
      in: "path"
      required: true
      schema:
        $ref: "#/components/schemas/ModelType"
    filterByConnectorAccessType:
      name: "accessType"
      description: "Filter by access type"
      in: "query"
      style: "form"
      explode: false
      schema:
        type: "array"
        items:
          $ref: "#/components/schemas/ConnectorAccessType"
    filterByProgressStatus:
      name: "status"
      description: "Filter by status"
      in: "query"
      style: "form"
      explode: false
      schema:
        type: "array"
        items:
          $ref: "#/components/schemas/ProgressStatus"
    filterBySearchTerm:
      name: "searchTerm"
      description: "Filter by search term"
      in: "query"
      style: "form"
      explode: false
      schema:
        type: "string"
    filterByOwnerId:
      name: "ownerId"
      description: "Filter by owner ID (either user or organization)"
      in: "query"
      style: "form"
      explode: false
      schema:
        type: array
        items:
          $ref: "#/components/schemas/AccountId"
    reportType:
      name: "reportType"
      description: "Synthetic dataset report type"
      in: "query"
      style: "form"
      schema:
        $ref: "#/components/schemas/SyntheticDatasetReportType"
    modelType:
      name: "modelType"
      description: "Model type"
      in: "query"
      style: "form"
      schema:
        $ref: "#/components/schemas/ModelType"
      required: true
    shortLivedFileToken:
      name: "slft"
      description: "A valid short-lived file token (`slft`) for accessing resource artefacts. See `metadata.shortLivedFileToken`."
      in: "query"
      style: "form"
      schema:
        type: "string"
      required: true
    generatorIdPath:
      name: "id"
      description: "The unique identifier of a generator."
      in: "path"
      required: true
      schema:
        type: "string"
    stepIdPath:
      name: "stepId"
      description: "The unique identifier of a step."
      in: "path"
      required: true
      schema:
        type: "string"
    sourceTableIdPath:
      name: "tableId"
      description: "The unique identifier of a source table."
      in: "path"
      required: true
      schema:
        type: "string"
    sourceColumnIdPath:
      name: "columnId"
      description: "The unique identifier of a source column."
      in: "path"
      required: true
      schema:
        type: "string"
    sourceForeignKeyIdPath:
      name: "foreignKeyId"
      description: "The unique identifier of a source foreign key."
      in: "path"
      required: true
      schema:
        type: "string"
    syntheticDatasetIdPath:
      name: "id"
      description: "The unique identifier of a synthetic dataset."
      in: "path"
      required: true
      schema:
        type: "string"
    syntheticTableIdPath:
      name: "tableId"
      description: "The unique identifier of a synthetic table."
      in: "path"
      required: true
      schema:
        type: "string"
    assistantThreadIdPath:
      name: "id"
      description: "The unique identifier of a assistant thread."
      in: "path"
      required: true
      schema:
        type: "string"
    computeIdPath:
      name: "id"
      description: "The unique identifier of a compute."
      in: "path"
      required: true
      schema:
        type: "string"
    userIdPath:
      name: "userId"
      in: "path"
      required: true
      description: "The ID of the user"
      schema:
        type: "string"
    organizationIdPath:
      name: "id"
      description: "The unique identifier of an organization"
      in: "path"
      required: true
      schema:
        $ref: "#/components/schemas/OrganizationId"
    inviteToken:
      name: "token"
      in: "query"
      required: true
      schema:
        type: "string"
        description: "The token for the invite"
    testConnection:
      name: "testConnection"
      description: |
        If true, the connection will be tested before saving. In case of error, the connector will not be saved.
        If false, the connection will not be tested.
      in: "query"
      schema:
        type: "boolean"
        default: true

  schemas:

    # SYSTEM
    AboutService:
      type: "object"
      description: "General information about the service."
      properties:
        version:
          type: "string"
          description: "The version number of the service."
          example: "4.0.0"
        assistant:
          type: "boolean"
          description: "A flag indicating if the assistant is enabled."

    # USERS
    User:
      type: "object"
      description: "A user of the service."
      properties:
        id:
          $ref: "#/components/schemas/UserId"
        name:
          $ref: "#/components/schemas/UserName"
        firstName:
          $ref: "#/components/schemas/UserFirstName"
        lastName:
          $ref: "#/components/schemas/UserLastName"
        email:
          $ref: "#/components/schemas/UserEmail"
        avatar:
          $ref: "#/components/schemas/UserAvatar"
    UserListItem:
      type: "object"
      description: "Essential information about a user for public listings."
      properties:
        id:
          $ref: "#/components/schemas/UserId"
        name:
          $ref: "#/components/schemas/UserName"
        avatar:
          $ref: "#/components/schemas/UserAvatar"
    UserId:
      type: "string"
      description: "The unique identifier of a user."
    UserName:
      type: "string"
      description: "The name of a user. As of now, it is the concatenation of the first name and last name."
    UserFirstName:
      type: "string"
      description: "First name of a user"
      maxLength: 30
    UserLastName:
      type: "string"
      description: "Last name of a user"
      maxLength: 30
    UserEmail:
      type: "string"
      description: "The email of a user"
    UserAvatar:
      type: "string"
      description: "The URL of the user's avatar"
    UserAvatarBase64:
      type: "string"
      description: "The base64-encoded image of the user's avatar"
    UserUnreadNotifications:
      type: "integer"
      description: "Number of unread notifications for the user"
    PermissionLevel:
      type: "string"
      description: |
        The permission level of the user with respect to this resource

        - `VIEW`: The user can view and use the resource
        - `ADMIN`: The user can edit, delete and transfer ownership of the resource
      enum:
      - "VIEW"
      - "ADMIN"
    UserLikeStatus:
      type: "boolean"
      description: A boolean indicating whether the user has liked the entity or not
    CurrentUser:
      type: "object"
      description: "Information on the current user."
      properties:
        id:
          $ref: "#/components/schemas/UserId"
        firstName:
          $ref: "#/components/schemas/UserFirstName"
        lastName:
          $ref: "#/components/schemas/UserLastName"
        email:
          $ref: "#/components/schemas/UserEmail"
        avatar:
          $ref: "#/components/schemas/UserAvatar"
        settings:
          $ref: "#/components/schemas/UserSettings"
        usage:
          $ref: "#/components/schemas/UserUsage"
        unreadNotifications:
          $ref: "#/components/schemas/UserUnreadNotifications"
        organizations:
          type: "array"
          description: "The organizations the user belongs to"
          items:
            $ref: "#/components/schemas/OrganizationListItem"
    UserSettings:
      type: "object"
      description: "Additional optional user settings."
      additionalProperties: { }
    UserSettingsUpdateConfig:
      type: "object"
      description: "The configuration for updating user settings."
      properties:
        profile:
          $ref: "#/components/schemas/UserSettingsProfileUpdateConfig"
        assistant:
          $ref: "#/components/schemas/UserSettingsAssistantUpdateConfig"
    UserSettingsProfileUpdateConfig:
      type: "object"
      properties:
        firstName:
          $ref: "#/components/schemas/UserFirstName"
        lastName:
          $ref: "#/components/schemas/UserLastName"
        avatar:
          $ref: "#/components/schemas/UserAvatarBase64"
    UserSettingsAssistantUpdateConfig:
      type: "object"
      properties:
        aboutUserMessage:
          description: "The instruction what the Assistant should know about the user to provide better response"
          type: "string"
        aboutModelMessage:
          description: "The instruction how the Assistant should respond"
          type: "string"
    UserUsage:
      type: "object"
      properties:
        credits:
          type: "object"
          properties:
            current:
              description: "The credit balance for the current time period"
              type: "number"
              format: "double"
            limit:
              description: "The credit limit for the current time period. If empty, then there is no limit."
              type: "number"
              format: "double"
            periodStart:
              description: "The UTC date and time when the current time period started"
              type: "string"
              format: "date-time"
            periodEnd:
              description: "The UTC date and time when the current time period ends"
              type: "string"
              format: "date-time"
        parallelTrainingJobs:
          type: "object"
          properties:
            current:
              description: "The number of currently running training jobs"
              type: "integer"
            limit:
              description: "The maximum number of running training jobs at any time. If empty, then there is no limit."
              type: "integer"
        parallelGenerationJobs:
          type: "object"
          properties:
            current:
              description: "The number of currently running generation jobs."
              type: "integer"
            limit:
              description: "The maximum number of running generation jobs at any time. If empty, then there is no limit."
              type: "integer"
    TransferOwnershipConfig:
      type: "object"
      description: "The configuration for transferring ownership of a resource to an account."
      properties:
        accountId:
          $ref: "#/components/schemas/AccountId"
    SetVisibilityConfig:
      type: "object"
      properties:
        visibility:
          $ref: "#/components/schemas/Visibility"
    Notification:
      type: "object"
      description: "A notification for a user."
      properties:
        id:
          type: "string"
          description: "The unique identifier of the notification."
        type:
          $ref: "#/components/schemas/NotificationType"
        message:
          type: "string"
          description: "The message of the notification."
        status:
          $ref: "#/components/schemas/NotificationStatus"
        createdAt:
          type: "string"
          format: "date-time"
          description: "The UTC date and time when the notification has been created."
        resourceUri:
          $ref: "#/components/schemas/NotificationResourceUri"
      required:
        - "id"
        - "type"
        - "message"
        - "status"
        - "createdAt"
    NotificationResourceUri:
      type: "string"
      description: "The service URI of the entity"
      example: "/generators/94c77249-42bf-443a-8e17-6e18a19d60b8"
    NotificationStatus:
      type: "string"
      description: "The status of the notification."
      enum:
        - "UNREAD"
        - "READ"
    NotificationType:
      type: "string"
      description: "The type of the notification"
      enum:
        - "RESOURCE_READY"
        - "RESOURCE_LIKED"
        - "RESOURCE_FAILED"
        - "MEMBER_JOINED"
    Metadata:
      type: "object"
      description: "The metadata of a resource."
      readOnly: true
      properties:
        creatorId:
          $ref: "#/components/schemas/UserId"
        creatorName:
          $ref: "#/components/schemas/UserName"
        createdAt:
          type: "string"
          description: "The UTC date and time when the resource has been created."
          format: "date-time"
          example: "2023‐09‐07T18:40:39Z"
        ownerId:
          $ref: "#/components/schemas/AccountId"
        ownerName:
          $ref: "#/components/schemas/AccountName"
        ownerType:
          $ref: "#/components/schemas/AccountType"
        ownerImage:
          $ref: "#/components/schemas/AccountImage"
        visibility:
          $ref: "#/components/schemas/Visibility"
        currentUserPermissionLevel:
          $ref: "#/components/schemas/PermissionLevel"
        currentUserLikeStatus:
          $ref: "#/components/schemas/UserLikeStatus"
        shortLivedFileToken:
          type: "string"
          description: |
            An auto-generated short-lived file token (`slft`) for accessing resource artefacts.
            The token is always restricted to a single resource, only valid for 60 minutes, and 
            only accepted by API endpoints that allow to download single files.
    PaginatedTotalCount:
      type: "integer"
      description: "The total number of entities within the list"

    # CONNECTOR
    ConnectorId:
      type: "string"
      description: "The unique identifier of a connector."
    ConnectorName:
      type: "string"
      description: "The name of a connector."
    ConnectorAccessType:
      type: "string"
      description: "The access type of a connector. Either `SOURCE` or `DESTINATION`."
      enum:
        - "SOURCE"
        - "DESTINATION"
      default: "SOURCE"
    ConnectorType:
      type: "string"
      description: |
        The type of a connector. 
        
        The type determines the structure of the config, secrets and ssl parameters.
        
        - `MYSQL`: MySQL database
        - `POSTGRES`: PostgreSQL database
        - `MSSQL`: Microsoft SQL Server database
        - `ORACLE`: Oracle database
        - `MARIADB`: MariaDB database
        - `SNOWFLAKE`: Snowflake cloud data platform
        - `BIGQUERY`: Google BigQuery cloud data warehouse
        - `HIVE`: Apache Hive database
        - `DATABRICKS`: Databricks cloud data platform
        - `AZURE_STORAGE`: Azure Blob Storage
        - `GOOGLE_CLOUD_STORAGE`: Google Cloud Storage
        - `S3_STORAGE`: Amazon S3 Storage
        - `FILE_UPLOAD`: File upload
      enum:
        - "MYSQL"
        - "POSTGRES"
        - "MSSQL"
        - "ORACLE"
        - "MARIADB"
        - "SNOWFLAKE"
        - "BIGQUERY"
        - "HIVE"
        - "DATABRICKS"
        - "AZURE_STORAGE"
        - "GOOGLE_CLOUD_STORAGE"
        - "S3_STORAGE"
        - "FILE_UPLOAD"
    ConnectorConfigParams:
      description: |
        The config parameters contain any configuration of the connector.
        The structure of the config object depends on the type of the connector.
      type: "object"
      additionalProperties: { }
    ConnectorSecretsParams:
      description: |
        The secrets parameters contain any sensitive credentials of the connector.
        The structure of the secrets object depends on the type of the connector.
      type: "object"
      additionalProperties:
        type: "string"
    ConnectorSslParams:
      description: |
        The ssl parameters contain any SSL related configurations of the connector.
        The structure of the ssl object depends on the type of the connector.
      type: "object"
      additionalProperties:
        type: "string"
    ConnectorUsage:
      type: "object"
      description: "Usage statistics of a connector."
      properties:
        noOfGenerators:
          type: "integer"
          description: "Number of generators using this connector."
    ConnectorListItem:
      type: "object"
      description: "Essential connector details for listings."
      properties:
        id:
          $ref: "#/components/schemas/ConnectorId"
        name:
          $ref: "#/components/schemas/ConnectorName"
        type:
          $ref: "#/components/schemas/ConnectorType"
        accessType:
          $ref: "#/components/schemas/ConnectorAccessType"
        metadata:
          $ref: "#/components/schemas/Metadata"
        usage:
          $ref: "#/components/schemas/ConnectorUsage"
      required:
        - "id"
        - "type"
    Connector:
      type: "object"
      description: |
        A connector is a connection to a data source or a data destination.
      properties:
        id:
          $ref: "#/components/schemas/ConnectorId"
        name:
          $ref: "#/components/schemas/ConnectorName"
        type:
          $ref: "#/components/schemas/ConnectorType"
        accessType:
          $ref: "#/components/schemas/ConnectorAccessType"
        config:
          $ref: "#/components/schemas/ConnectorConfigParams"
        secrets:
          $ref: "#/components/schemas/ConnectorSecretsParams"
        ssl:
          $ref: "#/components/schemas/ConnectorSslParams"
        metadata:
          $ref: "#/components/schemas/Metadata"
        usage:
          $ref: "#/components/schemas/ConnectorUsage"
        tableId:
          type: "string"
          description: |
            Optional. ID of a source table or a synthetic table, that this connector belongs to.
            If not set, then this connector is managed independently of any generator or synthetic dataset.
          default: null
      required:
        - "id"
        - "type"
    ConnectorConfig:
      type: "object"
      description: |
        The structures of the config, secrets and ssl parameters depend on the connector type.

        - Cloud storage:
          ```yaml
          - type: AZURE_STORAGE
            config:
              accountName: string
              clientId: string (required for auth via service principal)
              tenantId: string (required for auth via service principal)
            secrets:
              accountKey: string (required for regular auth)
              clientSecret: string (required for auth via service principal)

          - type: GOOGLE_CLOUD_STORAGE
            config:
            secrets:
              keyFile: string

          - type: S3_STORAGE
            config:
              accessKey: string
              endpointUrl: string (only needed for S3-compatible storage services other than AWS)
              sslEnabled: boolean, default: false
            secrets:
              secretKey: string
            ssl:
              caCertificate: base64-encoded string              
          ```
        - Database:
          ```yaml
          - type: BIGQUERY
            config:
            secrets:
              keyFile: string

          - type: DATABRICKS
            config:
              host: string
              httpPath: string
              catalog: string
              clientId: string (required for auth via service principal)
              tenantId: string (required for auth via service principal)
            secrets:
              accessToken: string (required for regular auth)
              clientSecret: string (required for auth via service principal)

          - type: HIVE
            config:
              host: string
              port: integer, default: 10000
              username: string (required for regular auth)
              kerberosEnabled: boolean, default: false
              kerberosServicePrincipal: string (required if kerberosEnabled)
              kerberosClientPrincipal: string (optional if kerberosEnabled)              
              kerberosKrb5Conf: string (required if kerberosEnabled)
              sslEnabled: boolean, default: false
            secrets:
              password: string (required for regular auth)
              kerberosKeytab: base64-encoded string (required if kerberosEnabled)
            ssl:
              caCertificate: base64-encoded string

          - type: MARIADB
            config:
              host: string
              port: integer, default: 3306
              username: string
            secrets:
              password: string

          - type: MSSQL
            config:
              host: string
              port: integer, default: 1433
              username: string
              database: string
            secrets:
             password: string

          - type: MYSQL
            config:
              host: string
              port: integer, default: 3306
              username: string
            secrets:
              password: string

          - type: ORACLE
            config:
              host: string
              port: integer, default: 1521
              username: string
              connectionType: enum {SID, SERVICE_NAME}, default: SID
              database: string, default: ORCL
            secrets:
              password: string

          - type: POSTGRES
            config:
              host: string
              port: integer, default: 5432
              username: string
              database: string
              sslEnabled: boolean, default: false
            secrets:
              password: string
            ssl:
              rootCertificate: base64-encoded string 
              sslCertificate: base64-encoded string
              sslCertificateKey: base64-encoded string

          - type: SNOWFLAKE
            config:
              account: string
              username: string
              warehouse: string, default: COMPUTE_WH
              database: string
            secrets:
              password: string
          ```
      properties:
        name:
          $ref: "#/components/schemas/ConnectorName"
        type:
          $ref: "#/components/schemas/ConnectorType"
        accessType:
          $ref: "#/components/schemas/ConnectorAccessType"
        config:
          $ref: "#/components/schemas/ConnectorConfigParams"
        secrets:
          $ref: "#/components/schemas/ConnectorSecretsParams"
        ssl:
          $ref: "#/components/schemas/ConnectorSslParams"
      required:
        - "type"
    ConnectorPatchConfig:
      type: "object"
      description: |
        See ConnectorConfig for details on the structure of the connection parameters.
      properties:
        name:
          $ref: "#/components/schemas/ConnectorName"
        config:
          $ref: "#/components/schemas/ConnectorConfigParams"
        secrets:
          $ref: "#/components/schemas/ConnectorSecretsParams"
        ssl:
          $ref: "#/components/schemas/ConnectorSslParams"

    # GENERATOR
    GeneratorId:
      type: "string"
      description: "The unique identifier of a generator."
    GeneratorName:
      type: "string"
      description: "The name of a generator."
    GeneratorDescription:
      type: "string"
      description: "The description of a generator."
    GeneratorAccuracy:
      type: "number"
      format: "double"
      description: |
        The overall accuracy of the trained generator.
        This is the average of the overall accuracy scores of all trained models.
    GeneratorTrainingTime:
      type: "string"
      description: "The UTC date and time when the training has finished."
      format: "date-time"
    GeneratorUsage:
      type: "object"
      description: "Usage statistics of a generator."
      properties:
        totalDatapoints:
          type: "integer"
          format: "int64"
          description: "The total number of datapoints generated by this generator."
        totalComputeTime:
          type: "integer"
          description: |
            The total compute time in seconds used for training this generator.
            This is the sum of the compute time of all trained tasks.
        noOfSyntheticDatasets:
          type: "integer"
          description: "Number of synthetic datasets generated by this generator."
        noOfLikes:
          type: "integer"
          description: "Number of likes of this generator."
    GeneratorListItem:
      type: "object"
      description: "Essential generator details for listings."
      properties:
        id:
          $ref: "#/components/schemas/GeneratorId"
        name:
          $ref: "#/components/schemas/GeneratorName"
        description:
          $ref: "#/components/schemas/GeneratorDescription"
        trainingStatus:
          $ref: "#/components/schemas/ProgressStatus"
        trainingTime:
          $ref: "#/components/schemas/GeneratorTrainingTime"
        usage:
          $ref: "#/components/schemas/GeneratorUsage"
        metadata:
          $ref: "#/components/schemas/Metadata"
        accuracy:
          $ref: "#/components/schemas/GeneratorAccuracy"
      required:
        - "id"
        - "trainingStatus"
    Generator:
      type: "object"
      description: |
        A generator is a set models that can generate synthetic data.
        
        The generator can be trained on one or more source tables. A quality assurance report is generated for each model.
      properties:
        id:
          $ref: "#/components/schemas/GeneratorId"
        name:
          $ref: "#/components/schemas/GeneratorName"
        description:
          $ref: "#/components/schemas/GeneratorDescription"
        trainingStatus:
          $ref: "#/components/schemas/ProgressStatus"
        trainingTime:
          $ref: "#/components/schemas/GeneratorTrainingTime"
        usage:
          $ref: "#/components/schemas/GeneratorUsage"
        metadata:
          $ref: "#/components/schemas/Metadata"
        accuracy:
          $ref: "#/components/schemas/GeneratorAccuracy"
        tables:
          type: "array"
          description: "The tables of this generator"
          items:
            $ref: "#/components/schemas/SourceTable"
      required:
        - "id"
        - "trainingStatus"
    # Source Table
    SourceTableId:
      type: "string"
      description: "The unique identifier of a source table."
    SourceTableName:
      type: "string"
      description: "The name of a source table. It must be unique within a generator."
      minLength: 1
      maxLength: 256
    SourceTablePrimaryKey:
      type: "string"
      description: "The column name of the primary key."
    SourceTableLocation:
      type: "string"
      description: |
        The location of a source table. Together with the source connector it uniquely
        identifies a source, and samples data from there.
    SourceTableTotalRows:
      type: "integer"
      description: |
        The total number of rows in the source table while fetching data for training.
    SourceTableData:
      type: "string"
      description: |
        The base64-encoded string derived from a Parquet file containing the specified source table.
    SourceTableIncludeChildren:
      type: "boolean"
      description: |
        If true, all tables that are referenced by foreign keys will
        be included. If false, only the selected table will be included.
      default: false
    SourceTable:
      type: "object"
      description: "A table as part of a generator."
      properties:
        id:
          $ref: "#/components/schemas/SourceTableId"
        sourceConnectorId:
          $ref: "#/components/schemas/ConnectorId"
        location:
          $ref: "#/components/schemas/SourceTableLocation"
        name:
          $ref: "#/components/schemas/SourceTableName"
        primaryKey:
          $ref: "#/components/schemas/SourceTablePrimaryKey"
        columns:
          type: "array"
          description: "The columns of this generator table."
          items:
            $ref: "#/components/schemas/SourceColumn"
        foreignKeys:
          type: "array"
          description: "The foreign keys of a table."
          items:
            $ref: "#/components/schemas/SourceForeignKey"
        tabularModelMetrics:
          $ref: "#/components/schemas/ModelMetrics"
        languageModelMetrics:
          $ref: "#/components/schemas/ModelMetrics"
        tabularModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        languageModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        totalRows:
          $ref: "#/components/schemas/SourceTableTotalRows"
      required:
        - "id"
        - "name"
    # Source Column
    SourceColumnId:
      type: "string"
      readOnly: true
      description: "The unique identifier of a source column."
    SourceColumnName:
      type: "string"
      description: "The name of a source column. It must be unique within a source table."
      minLength: 1
      maxLength: 256
    SourceColumnIncluded:
      type: "boolean"
      default: true
      description: |
        If true, the column will be included in the training.
        If false, the column will be excluded from the training.
    Probe:
      type: "object"
      description: "The generated synthetic samples returned as a result of the probe."
      properties:
        name:
          type: "string"
          description: "The name of the table."
        rows:
          $ref: "#/components/schemas/Samples"
    Samples:
      type: "array"
      items:
        type: "object"
        additionalProperties: true
    SourceColumnValueRange:
      description: |
        The (privacy-safe) range of values detected within a source column. These values can then be used as seed values
        for conditional generation. For CATEGORICAL and NUMERIC_DISCRETE encoding types, this will be given as a list
        of unique values, sorted by popularity. For other NUMERIC and for DATETIME encoding types, this will be given
        as a min and max value. Note, that this property will only be populated, once the analysis step for the training
        of the generator has been completed.
      type: "object"
      properties:
        min:
          type: "string"
          description: "The minimum value of the column. For dates, this is represented in ISO format."
        max:
          type: "string"
          description: "The maximum value of the column. For dates, this is represented in ISO format."
        values:
          type: "array"
          description: "The list of distinct values of the column. Limited to a maximum of 1000 values."
          items:
            type: "string"
        has_null:
          type: "boolean"
          description: "If true, null value was detected within the column."
    SourceColumn:
      type: "object"
      description: "A column as part of a source table."
      properties:
        id:
          $ref: "#/components/schemas/SourceColumnId"
        name:
          $ref: "#/components/schemas/SourceColumnName"
        included:
          $ref: "#/components/schemas/SourceColumnIncluded"
        modelEncodingType:
          $ref: "#/components/schemas/ModelEncodingType"
        valueRange:
          $ref: "#/components/schemas/SourceColumnValueRange"
      required:
        - "id"
        - "name"
        - "modelEncodingType"
    # Source ForeignKey
    SourceForeignKeyId:
      type: "string"
      readOnly: true
      description: "The unique identifier of a foreign key."
    ForeignKeyColumn:
      type: "string"
      description: "The column name of a foreign key."
      minLength: 1
    ForeignKeyReferencedTable:
      type: "string"
      description: "The table name of the referenced table. That table must have a primary key already defined."
      minLength: 1
    ForeignKeyIsContext:
      type: "boolean"
      description: |
        If true, then the foreign key will be considered as a context relation.
        Note, that only one foreign key relation per table can be a context relation.
    SourceForeignKey:
      type: "object"
      properties:
        id:
          $ref: "#/components/schemas/SourceForeignKeyId"
        column:
          $ref: "#/components/schemas/ForeignKeyColumn"
        referencedTable:
          $ref: "#/components/schemas/ForeignKeyReferencedTable"
        isContext:
          $ref: "#/components/schemas/ForeignKeyIsContext"
      required:
        - "id"
        - "column"
        - "referencedTable"
        - "isContext"
    # Generator Configs
    GeneratorConfig:
      type: "object"
      description: "The configuration for creating a new generator."
      properties:
        name:
          $ref: "#/components/schemas/GeneratorName"
        description:
          $ref: "#/components/schemas/GeneratorDescription"
        tables:
          type: "array"
          description: "The tables of a generator"
          items:
            $ref: "#/components/schemas/SourceTableConfig"
    GeneratorCloneConfig:
      type: "object"
      description: "The configuration for cloning a generator."
      properties:
        trainingStatus:
          $ref: "#/components/schemas/GeneratorCloneTrainingStatus"
    GeneratorCloneTrainingStatus:
      description: |
        The training status of the new generator. The available options are:
        
        - `NEW`: The new generator will re-use existing data and model configurations.
        - `CONTINUE`: The new generator will re-use existing data and model configurations, as well as model weights.
      enum:
        - "NEW"
        - "CONTINUE"
      default: "NEW"
    GeneratorPatchConfig:
      type: "object"
      description: "The configuration for updating a generator."
      properties:
        name:
          $ref: "#/components/schemas/GeneratorName"
        description:
          $ref: "#/components/schemas/GeneratorDescription"
    GeneratorImportFromFileConfig:
      type: "object"
      properties:
        file:
          type: "string"
          format: "binary"
      required:
        - "file"
    SourceTableConfig:
      type: "object"
      description: "The configuration for a source table when creating a new generator."
      properties:
        name:
          $ref: "#/components/schemas/SourceTableName"
        sourceConnectorId:
          $ref: "#/components/schemas/ConnectorId"
        location:
          $ref: "#/components/schemas/SourceTableLocation"
        data:
          $ref: "#/components/schemas/SourceTableData"
        tabularModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        languageModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        primaryKey:
          $ref: "#/components/schemas/SourceTablePrimaryKey"
        foreignKeys:
          type: "array"
          description: "The foreign key configurations of this table."
          items:
            $ref: "#/components/schemas/SourceForeignKeyConfig"
        columns:
          type: "array"
          description: "The column configurations of this table."
          items:
            $ref: "#/components/schemas/SourceColumnConfig"
      required:
        - "name"
    SourceTablePatchConfig:
      type: "object"
      description: "The configuration for updating a source table."
      properties:
        name:
          $ref: "#/components/schemas/SourceTableName"
        primaryKey:
          $ref: "#/components/schemas/SourceTablePrimaryKey"
        tabularModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        languageModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
    SourceForeignKeyConfig:
      type: "object"
      properties:
        column:
          $ref: "#/components/schemas/ForeignKeyColumn"
        referencedTable:
          $ref: "#/components/schemas/ForeignKeyReferencedTable"
        isContext:
          $ref: "#/components/schemas/ForeignKeyIsContext"
      required:
        - "column"
        - "referencedTable"
        - "isContext"
    SourceForeignKeyPatchConfig:
      type: "object"
      properties:
        isContext:
          $ref: "#/components/schemas/ForeignKeyIsContext"
    SourceColumnConfig:
      type: "object"
      description: "The configuration for a source column when creating a new generator."
      properties:
        name:
          $ref: "#/components/schemas/SourceColumnName"
        modelEncodingType:
          $ref: "#/components/schemas/ModelEncodingType"
      required:
        - "name"
    SourceColumnPatchConfig:
      type: "object"
      description: "The configuration for updating a source column."
      properties:
        included:
          $ref: "#/components/schemas/SourceColumnIncluded"
        modelEncodingType:
          $ref: "#/components/schemas/ModelEncodingType"
    SourceTableAddConfig:
      type: "object"
      description: "The configuration for adding a new source table to a generator."
      properties:
        sourceConnectorId:
          $ref: "#/components/schemas/ConnectorId"
        location:
          $ref: "#/components/schemas/SourceTableLocation"
        name:
          $ref: "#/components/schemas/SourceTableName"
        includeChildren:
          $ref: "#/components/schemas/SourceTableIncludeChildren"
        tabularModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
        languageModelConfiguration:
          $ref: "#/components/schemas/ModelConfiguration"
      required:
        - "sourceConnectorId"
        - "location"

    # MODEL
    ModelId:
      type: "string"
      description: "The model to be used for training."
      example:
        - MOSTLY_AI/Small
        - MOSTLY_AI/Medium
        - MOSTLY_AI/Large
        - MOSTLY_AI/LSTMFromScratch-3m
        - microsoft/phi-1_5
    ModelConfiguration:
      type: "object"
      description: "The training configuration for the model"
      properties:
        model:
          $ref: "#/components/schemas/ModelId"
        maxSampleSize:
          type: "integer"
          description: |
            The maximum number of samples to consider for training.
            If not provided, then all available samples will be taken.
          minimum: 1
          maximum: 1000000000
        batchSize:
          type: "integer"
          description: |
            The batch size used for training the model.
            If not provided, batchSize will be chosen automatically.
          minimum: 1
          maximum: 1000000
        maxTrainingTime:
          type: "number"
          format: "double"
          description: The maximum number of minutes to train the model.
          default: 14400
          minimum: 0
          maximum: 1000000
        maxEpochs:
          type: "number"
          format: "double"
          description: The maximum number of epochs to train the model.
          default: 100
          minimum: 0
          maximum: 1000000
        maxSequenceWindow:
          type: "integer"
          description: |
            The maximum sequence window to consider for training.
            Only applicable for TABULAR models.
          default: 100
          minimum: 1
          maximum: 100000
        enableFlexibleGeneration:
          type: "boolean"
          description: |
            If true, then the trained generator can be used for rebalancing and imputation.
            Only applicable for TABULAR models.
          default: true
        valueProtection:
          description: |
            Defines if Rare Category, Extreme value, or Sequence length protection will be applied.
          type: "boolean"
          default: true
        rareCategoryReplacementMethod:
          description: |
            Specifies how rare categories will be sampled.
            Only applicable if value protection has been enabled.
            
            - `CONSTANT`: Replace rare categories by a constant `_RARE_` token.
            - `SAMPLE`: Replace rare categories by a sample from non-rare categories.
          type: "string"
          enum:
            - "CONSTANT"
            - "SAMPLE"
          default: "CONSTANT"
        differentialPrivacy:
          $ref: "#/components/schemas/DifferentialPrivacyConfig"
        compute:
          $ref: "#/components/schemas/ComputeId"

    # JOB_PROGRESS
    JobProgress:
      type: "object"
      description: "The progress of a job."
      properties:
        id:
          type: "string"
        startDate:
          type: "string"
          description: |
            The UTC date and time when the job has started.
            If the job has not started yet, then this is None.
          example: "2024-01-25T12:34:56Z"
          format: "date-time"
        endDate:
          type: "string"
          description: |
            The UTC date and time when the job has ended.
            If the job is still, then this is None.
          example: "2024-01-25T12:34:56Z"
          format: "date-time"
        progress:
          $ref: "#/components/schemas/ProgressValue"
        status:
          $ref: "#/components/schemas/ProgressStatus"
        steps:
          type: "array"
          items:
            $ref: "#/components/schemas/ProgressStep"
    ProgressStep:
      type: "object"
      description: "The progress of a step."
      properties:
        id:
          type: "string"
          description: "The unique identifier of the step."
        modelLabel:
          type: "string"
          description: |
            The unique label for the model, consisting of table name and a suffix for the model type.
            This will be empty for steps that are not related to a model.
          example:
            - "census:tabular"
            - "census:language"
        computeName:
          $ref: "#/components/schemas/ComputeName"
        restarts:
          type: "integer"
          format: "int32"
          description: "The number of previous restarts for the corresponding task."
          default: 0
        taskType:
          $ref: "#/components/schemas/TaskType"
        stepCode:
          $ref: "#/components/schemas/StepCode"
        startDate:
          type: "string"
          description: |
            The UTC date and time when the job has started.
            If the job has not started yet, then this is None.
          example: "2024-01-25T12:34:56Z"
          format: "date-time"
        endDate:
          type: "string"
          description: |
            The UTC date and time when the job has ended.
            If the job is still, then this is None.
          example: "2024-01-25T12:34:56Z"
          format: "date-time"
        messages:
          type: "array"
          items:
            type: "object"
            additionalProperties: { }
        errorMessage:
          type: "string"
        progress:
          $ref: "#/components/schemas/ProgressValue"
        status:
          $ref: "#/components/schemas/ProgressStatus"
    TaskType:
      type: "string"
      description: "The type of the task."
      enum:
        - "SYNC"
        - "TRAIN_TABULAR"
        - "TRAIN_LANGUAGE"
        - "FINALIZE_TRAINING"
        - "GENERATE_TABULAR"
        - "GENERATE_LANGUAGE"
        - "FINALIZE_GENERATION"
        - "PROBE_TABULAR"
        - "PROBE_LANGUAGE"
        - "FINALIZE_PROBING"
    StepCode:
      type: "string"
      description: "The unique code for the step."
      enum:
        - "PULL_TRAINING_DATA"
        - "ANALYZE_TRAINING_DATA"
        - "ENCODE_TRAINING_DATA"
        - "TRAIN_MODEL"
        - "GENERATE_MODEL_REPORT_DATA"
        - "CREATE_MODEL_REPORT"
        - "FINALIZE_TRAINING"
        - "GENERATE_DATA"
        - "CREATE_DATA_REPORT"
        - "FINALIZE_GENERATION"
        - "DELIVER_DATA"
        - "FINALIZE_PROBING"
    ProgressValue:
      type: "object"
      properties:
        value:
          type: "integer"
          default: 0
        max:
          type: "integer"
          default: 1
    ProgressStatus:
      type: "string"
      description: |
        The status of a job or a step.
        
        - `NEW`: The job/step is being configured, and has not started yet
        - `CONTINUE`: The job/step is being configured, but has existing artefacts
        - `ON_HOLD`: The job/step has been started, but is kept on hold
        - `QUEUED`: The job/step has been started, and is awaiting for resources to execute
        - `IN_PROGRESS`: The job/step is currently running
        - `DONE`: The job/step has finished successfully
        - `FAILED`: The job/step has failed
        - `CANCELED`: The job/step has been canceled
      enum:
        - "NEW"
        - "CONTINUE"
        - "ON_HOLD"
        - "QUEUED"
        - "IN_PROGRESS"
        - "DONE"
        - "FAILED"
        - "CANCELED"

    # SYNTHETIC DATASET
    SyntheticDatasetId:
      type: "string"
      description: "The unique identifier of a synthetic dataset."
    SyntheticDatasetName:
      type: "string"
      description: "The name of a synthetic dataset."
    SyntheticDatasetDescription:
      type: "string"
      description: "The description of a synthetic dataset."
    SyntheticDatasetGenerationTime:
      type: "string"
      description: "The UTC date and time when the generation has finished."
      format: "date-time"
    SyntheticDatasetUsage:
      type: "object"
      description: "Usage statistics of a synthetic dataset."
      properties:
        totalDatapoints:
          type: "integer"
          format: "int64"
          description: "The number of datapoints in the synthetic dataset"
        totalCredits:
          type: "number"
          format: "double"
          description: "The number of credits used for the synthetic dataset"
        totalComputeTime:
          type: "integer"
          description: |
            The total compute time in seconds used for generating this synthetic dataset.
            This is the sum of the compute time of all trained tasks.
        noOfLikes:
          type: "integer"
          description: "Number of likes of this synthetic dataset."
    SyntheticDatasetListItem:
      type: "object"
      description: "Essential synthetic dataset details for listings."
      properties:
        id:
          $ref: "#/components/schemas/SyntheticDatasetId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        name:
          $ref: "#/components/schemas/SyntheticDatasetName"
        description:
          $ref: "#/components/schemas/SyntheticDatasetDescription"
        generationStatus:
          $ref: "#/components/schemas/ProgressStatus"
        generationTime:
          $ref: "#/components/schemas/SyntheticDatasetGenerationTime"
        usage:
          $ref: "#/components/schemas/SyntheticDatasetUsage"
      required:
        - "id"
        - "generationStatus"
    SyntheticDataset:
      type: "object"
      description: |
        A synthetic dataset is created based on a trained generator. 
        
        It consists of synthetic samples, as well as a quality assurance report.
      properties:
        id:
          $ref: "#/components/schemas/SyntheticDatasetId"
        generatorId:
          $ref: "#/components/schemas/GeneratorId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        name:
          $ref: "#/components/schemas/SyntheticDatasetName"
        description:
          $ref: "#/components/schemas/SyntheticDatasetDescription"
        generationStatus:
          $ref: "#/components/schemas/ProgressStatus"
        generationTime:
          $ref: "#/components/schemas/SyntheticDatasetGenerationTime"
        tables:
          type: "array"
          description: "The tables of this synthetic dataset."
          items:
            $ref: "#/components/schemas/SyntheticTable"
        delivery:
          $ref: "#/components/schemas/SyntheticDatasetDelivery"
        accuracy:
          $ref: "#/components/schemas/GeneratorAccuracy"
        usage:
          $ref: "#/components/schemas/SyntheticDatasetUsage"
      required:
        - "id"
        - "generationStatus"
    SyntheticDatasetFormat:
      type: "string"
      enum:
        - "CSV"
        - "PARQUET"
        - "XLSX"
      default: "CSV"
    SyntheticDatasetReportType:
      type: "string"
      enum:
        - "MODEL"
        - "DATA"
      default: "DATA"
    # Synthetic Table
    SyntheticTableSampleSize:
      type: "integer"
      description: |
        Number of generated samples. Only applicable for subject tables.
        If neither size nor seed is provided, then the default behavior for Synthetic Datasets is to generate the
        same size of samples as the original, and the default behavior for Synthetic Probes is to generate one
        subject only.
      minimum: 1
    SamplingTemperature:
      description: "temperature for sampling"
      type: "number"
      format: "double"
      minimum: 0.0
      maximum: 2.0
      default: 1.0
    SamplingTopP:
      description: "topP for sampling"
      type: "number"
      format: "double"
      minimum: 0.9
      maximum: 1.0
      default: 1.0
    SyntheticTableSampleSeedConnectorId:
      description: |
        The connector id of the seed data for conditional generation.
        Only applicable for subject tables.
      type: "string"
      readOnly: true
    SyntheticTableSampleSeedDict:
      type: "string"
      description: |
        The base64-encoded string derived from a json line file containing the specified sample seed data.
        This allows conditional live probing via non-python clients.
    SyntheticTableSampleSeedData:
      type: "string"
      description: |
        The base64-encoded string derived from a Parquet file containing the specified sample seed data.
        This allows conditional generation as well as live probing via python clients.
    SyntheticTableConfiguration:
      type: "object"
      description: "The sample configuration for a synthetic table"
      properties:
        sampleSize:
          $ref: "#/components/schemas/SyntheticTableSampleSize"
        sampleSeedConnectorId:
          $ref: "#/components/schemas/SyntheticTableSampleSeedConnectorId"
        sampleSeedDict:
          $ref: "#/components/schemas/SyntheticTableSampleSeedDict"
        sampleSeedData:
          $ref: "#/components/schemas/SyntheticTableSampleSeedData"
        samplingTemperature:
          $ref: "#/components/schemas/SamplingTemperature"
        samplingTopP:
          $ref: "#/components/schemas/SamplingTopP"
        rebalancing:
          $ref: "#/components/schemas/RebalancingConfig"
        imputation:
          $ref: "#/components/schemas/ImputationConfig"
        fairness:
          $ref: "#/components/schemas/FairnessConfig"
        tabularCompute:
          $ref: "#/components/schemas/ComputeId"
        languageCompute:
          $ref: "#/components/schemas/ComputeId"
    SyntheticTableId:
      type: "string"
      description: "The unique identifier of a synthetic table."
    SyntheticTableName:
      type: "string"
      description: "The name of a synthetic table. This matches the name of a corresponding SourceTable."
    SyntheticTableTotalRows:
      type: "integer"
      description: |
        The total number of rows for that table in the generated synthetic dataset.
    SyntheticTableTotalDatapoints:
      type: "integer"
      description: |
        The total number of datapoints for that table in the generated synthetic dataset.
    SyntheticTable:
      type: "object"
      description: "A synthetic table that will be generated."
      properties:
        id:
          $ref: "#/components/schemas/SyntheticTableId"
        name:
          $ref: "#/components/schemas/SourceTableName"
        configuration:
          $ref: "#/components/schemas/SyntheticTableConfiguration"
        tabularModelMetrics:
          $ref: "#/components/schemas/ModelMetrics"
        languageModelMetrics:
          $ref: "#/components/schemas/ModelMetrics"
        foreignKeys:
          type: "array"
          description: "The foreign keys of a table."
          items:
            $ref: "#/components/schemas/SourceForeignKey"
        totalRows:
          $ref: "#/components/schemas/SyntheticTableTotalRows"
        totalDatapoints:
          $ref: "#/components/schemas/SyntheticTableTotalDatapoints"
        sourceTableTotalRows:
          $ref: "#/components/schemas/SourceTableTotalRows"
      required:
        - "name"
    # Delivery
    SyntheticDatasetDelivery:
      type: "object"
      properties:
        overwriteTables:
          description: |
            If true, tables in the destination will be overwritten.
            If false, any tables exist, the delivery will fail.
          type: "boolean"
          default: false
        destinationConnectorId:
          $ref: "#/components/schemas/ConnectorId"
        location:
          type: "string"
          description: "The location for the destination connector."
      required:
        - "destinationConnectorId"
        - "location"
        - "overwriteTables"
    # Synthetic Dataset Configs
    SyntheticDatasetConfig:
      type: "object"
      description: "The configuration for creating a new synthetic dataset."
      properties:
        generatorId:
          $ref: "#/components/schemas/GeneratorId"
        name:
          $ref: "#/components/schemas/SyntheticDatasetName"
        description:
          $ref: "#/components/schemas/SyntheticDatasetDescription"
        tables:
          type: "array"
          items:
            $ref: "#/components/schemas/SyntheticTableConfig"
        delivery:
          $ref: "#/components/schemas/SyntheticDatasetDelivery"
    SyntheticDatasetPatchConfig:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/SyntheticDatasetName"
        description:
          $ref: "#/components/schemas/SyntheticDatasetDescription"
        delivery:
          $ref: "#/components/schemas/SyntheticDatasetDelivery"
    SyntheticTablePatchConfig:
      type: "object"
      description: "The configuration for updating a synthetic table."
      properties:
        configuration:
          $ref: "#/components/schemas/SyntheticTableConfiguration"
    SyntheticProbeConfig:
      type: "object"
      description: "The configuration for probing for new synthetic samples."
      properties:
        generatorId:
          $ref: "#/components/schemas/GeneratorId"
        tables:
          type: "array"
          items:
            $ref: "#/components/schemas/SyntheticTableConfig"
    SyntheticTableConfig:
      type: "object"
      description: "The configuration for a synthetic table when creating a new synthetic dataset."
      properties:
        name:
          $ref: "#/components/schemas/SyntheticTableName"
        configuration:
          $ref: "#/components/schemas/SyntheticTableConfiguration"
      required:
        - "name"

    # ASSISTANT
    AssistantSettingsIsEnabled:
      type: "boolean"
      description: "If true, the assistant is enabled."
    AssistantLiteLlmModel:
      type: "string"
      description: "The LiteLLM model of the assistant. See https://docs.litellm.ai/docs/providers."
      example:
        - "openai/gpt-3.5-turbo"
        - "mistral/mistral-tiny"
    AssistantLiteLlmApiKey:
      type: "string"
      description: "The API key for the selected LiteLLM model. See https://docs.litellm.ai/docs/providers."
    AssistantLiteLlmExtra:
      description: "Any additional configuration parameters for the selected LiteLLM model. See https://docs.litellm.ai/docs/providers."
      type: "array"
      items:
        type: "object"
        properties:
          key:
            type: "string"
          value:
            type: "string"
    AssistantDataLlmApiKey:
      type: "string"
      description: "The API key for the DataLLM service. See https://data.mostly.ai."
    AssistantSystemInstructions:
      description: "The system instructions of the assistant"
      type: "string"
    AssistantCustomInstructions:
      description: "The custom instructions of the assistant"
      type: "string"
    AssistantSettings:
      type: "object"
      description: "Additional optional assistant settings used for LiteLLM"
      properties:
        isEnabled:
          $ref: "#/components/schemas/AssistantSettingsIsEnabled"
        liteLlm:
          type: "object"
          properties:
            model:
              $ref: "#/components/schemas/AssistantLiteLlmModel"
            apiKey:
              $ref: "#/components/schemas/AssistantLiteLlmApiKey"
            extra:
              $ref: "#/components/schemas/AssistantLiteLlmExtra"
        dataLlm:
          type: "object"
          properties:
            apiKey:
              $ref: "#/components/schemas/AssistantDataLlmApiKey"
        systemInstructions:
          $ref: "#/components/schemas/AssistantSystemInstructions"
        customInstructions:
          $ref: "#/components/schemas/AssistantCustomInstructions"
        defaultSystemInstructions:
          $ref: "#/components/schemas/AssistantSystemInstructions"
    AssistantThreadId:
      type: "string"
      description: "The unique identifier of a assistant thread."
    AssistantThreadName:
      type: "string"
      description: "The name of a assistant thread."
    AssistantThreadSessionStatus:
      type: "string"
      enum:
        - "initializing"
        - "running"
        - "expired"
    AssistantThreadListItem:
      type: "object"
      description: "Essential assistant thread details for listings."
      properties:
        id:
          $ref: "#/components/schemas/AssistantThreadId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        name:
          $ref: "#/components/schemas/AssistantThreadName"
        usage:
          $ref: "#/components/schemas/AssistantThreadUsage"
      required:
        - "id"
    AssistantThread:
      type: "object"
      description: "A assistant thread."
      properties:
        id:
          $ref: "#/components/schemas/AssistantThreadId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        name:
          $ref: "#/components/schemas/AssistantThreadName"
        sessionStatus:
          $ref: "#/components/schemas/AssistantThreadSessionStatus"
        messages:
          type: "array"
          description: |
            List of all existing messages, excluding any system message.
            Example:
              What's the square root of 9?   role: user        type: text
              ok, I will write some python   role: assistant   type: text
              r = math.sqrt(9)\nr            role: assistant   type: python
              3                              role: tool        type: console
              The answer is 3!               role: assistant   type: text
              Plot me a random barplot       role: user        type: text
              ... plt.savefig() ...          role: assistant   type: python
              Here is ![img]() ...           role: assistant   type: text
              Write me a random file         role: user        type: text
              ... .to_csv() ...              role: assistant   type: python
              Here is [file]() ...           role: assistant   type: text
          items:
            $ref: "#/components/schemas/AssistantMessage"
        usage:
          $ref: "#/components/schemas/AssistantThreadUsage"
      required:
        - "id"
    AssistantMessageId:
      type: "string"
      description: "The unique identifier of a assistant message."
    AssistantMessageRole:
      type: "string"
      description: "The role of the author of this message"
      enum:
        - "system"
        - "user"
        - "assistant"
        - "tool"
        - "heartbeat"
    AssistantMessageContentType:
      type: "string"
      description: "The type of the message content"
      enum:
        - "text"
        - "python"
        - "console"
        - "file"
    AssistantMessageContent:
      type: "string"
      minLength: 0
      description: "The content of a message"
    AssistantMessageContentDelta:
      type: "string"
      minLength: 0
      description: "The partial content of a message"
    AssistantMessageFinishReason:
      type: "string"
      enum:
        - "stop"
        - "length"
        - "tool_calls"
    AssistantMessage:
      type: "object"
      description: "A complete message."
      properties:
        id:
          $ref: "#/components/schemas/AssistantMessageId"
        role:
          $ref: "#/components/schemas/AssistantMessageRole"
        contentType:
          $ref: "#/components/schemas/AssistantMessageContentType"
        content:
          $ref: "#/components/schemas/AssistantMessageContent"
        finishReason:
          $ref: "#/components/schemas/AssistantMessageFinishReason"
        tokensConsumed:
          type: "integer"
          format: "int64"
          description: "The number of tokens consumed by the assistant message."
    AssistantMessageDelta:
      type: "object"
      description: "A partial message delta generated by streamed model responses."
      properties:
        id:
          $ref: "#/components/schemas/AssistantMessageId"
        role:
          $ref: "#/components/schemas/AssistantMessageRole"
        contentType:
          $ref: "#/components/schemas/AssistantMessageContentType"
        delta:
          $ref: "#/components/schemas/AssistantMessageContentDelta"
        finishReason:
          $ref: "#/components/schemas/AssistantMessageFinishReason"
        tokensConsumed:
          type: "integer"
          format: "int64"
          description: "The number of tokens consumed by the model."
    AssistantThreadUsage:
      type: "object"
      properties:
        totalTokensConsumed:
          type: "integer"
          format: "int64"
          description: "The total number of tokens consumed by the thread."
    # Assistant Configs
    AssistantThreadConfig:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/AssistantThreadName"
    AssistantThreadPatchConfig:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/AssistantThreadName"
    AssistantMessageConfig:
      type: "object"
      description: "Submit a new message"
      properties:
        stream:
          type: "boolean"
          default: true
          nullable: true
          description: "Whether to stream back partial progress. If set, message deltas will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a data: [DONE] message."
        content:
          $ref: "#/components/schemas/AssistantMessageContent"
        contentType:
          $ref: "#/components/schemas/AssistantMessageContentType"

    # COMPUTES
    ComputeId:
      type: "string"
      description: "The unique identifier of a compute resource. Not applicable for SDK."
    ComputeName:
      type: "string"
      description: "The name of a compute resource."
      minLength: 1
    ComputeType:
      type: "string"
      description: "The type of compute."
      enum:
        - "KUBERNETES"
        - "DATABRICKS"
    ComputeOrderIndex:
      type: "integer"
      description: "The index for determining the sort order when listing computes"
    ComputeResources:
      type: "object"
      description: "A set of available hardware resources for a compute resource."
      properties:
        cpus:
          type: "integer"
          description: "The number of CPU cores"
        memory:
          type: "number"
          format: "double"
          description: "The amount of memory in GB"
        gpus:
          type: "integer"
          description: "The number of GPUs"
          default: 0
        gpuMemory:
          type: "number"
          format: "double"
          description: "The amount of GPU memory in GB"
          default: 0
    ComputeConfigParams:
      type: "object"
      additionalProperties: { }
    ComputeSecretsParams:
      type: "object"
      additionalProperties: { }
    ComputeListItem:
      type: "object"
      description: "Essential compute details for listings."
      properties:
        id:
          $ref: "#/components/schemas/ComputeId"
        type:
          $ref: "#/components/schemas/ComputeType"
        name:
          $ref: "#/components/schemas/ComputeName"
        resources:
          $ref: "#/components/schemas/ComputeResources"
    Compute:
      type: "object"
      description: "A compute resource for executing tasks."
      properties:
        id:
          $ref: "#/components/schemas/ComputeId"
        name:
          $ref: "#/components/schemas/ComputeName"
        type:
          $ref: "#/components/schemas/ComputeType"
        config:
          $ref: "#/components/schemas/ComputeConfigParams"
        secrets:
          $ref: "#/components/schemas/ComputeSecretsParams"
        resources:
          $ref: "#/components/schemas/ComputeResources"
        orderIndex:
          $ref: "#/components/schemas/ComputeOrderIndex"
    # Compute Configs
    ComputeConfig:
      type: "object"
      description: "The configuration for creating a new compute resource."
      properties:
        name:
          $ref: "#/components/schemas/ComputeName"
        type:
          $ref: "#/components/schemas/ComputeType"
        resources:
          $ref: "#/components/schemas/ComputeResources"
        config:
          $ref: "#/components/schemas/ComputeConfigParams"
        secrets:
          $ref: "#/components/schemas/ComputeSecretsParams"
        orderIndex:
          $ref: "#/components/schemas/ComputeOrderIndex"
    ComputePatchConfig:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/ComputeName"
        type:
          $ref: "#/components/schemas/ComputeType"
        resources:
          $ref: "#/components/schemas/ComputeResources"
        config:
          $ref: "#/components/schemas/ComputeConfigParams"
        secrets:
          $ref: "#/components/schemas/ComputeSecretsParams"
        orderIndex:
          $ref: "#/components/schemas/ComputeOrderIndex"

    # ORGANIZATIONS
    OrganizationId:
      type: "string"
      description: "The unique identifier of an organization."
    OrganizationName:
      type: "string"
      description: | 
        The name of an organization.
        Contains only alphanumeric characters, hyphens, and underscores. Must start or end with alphanumeric.
        It must be globally case-insensitive unique.
      maxLength: 64
    OrganizationDisplayName:
      type: "string"
      description: "The display name of an organization."
    OrganizationDescription:
      type: "string"
      description: "The description of an organization. Supports markdown."
    OrganizationLogo:
      type: "string"
      description: "The URL of the organization's logo."
    OrganizationLogoBase64:
      type: "string"
      description: "The base64-encoded image of the organization's logo."
    OrganizationEmail:
      type: "string"
      description: "The email address of the organization."
    OrganizationWebsite:
      type: "string"
      description: "The URL of the organization's website."
    OrganizationListItem:
      type: "object"
      description: "Essential organization details for listings."
      properties:
        id:
          $ref: "#/components/schemas/OrganizationId"
        name:
          $ref: "#/components/schemas/OrganizationName"
        displayName:
          $ref: "#/components/schemas/OrganizationDisplayName"
        description:
          $ref: "#/components/schemas/OrganizationDescription"
        logo:
          $ref: "#/components/schemas/OrganizationLogo"
      required:
        - "id"
        - "displayName"
    Organization:
      type: "object"
      description: "An organization that owns resources."
      properties:
        id:
          $ref: "#/components/schemas/OrganizationId"
        name:
          $ref: "#/components/schemas/OrganizationName"
        displayName:
          $ref: "#/components/schemas/OrganizationDisplayName"
        description:
          $ref: "#/components/schemas/OrganizationDescription"
        logo:
          $ref: "#/components/schemas/OrganizationLogo"
        email:
          $ref: "#/components/schemas/OrganizationEmail"
        website:
          $ref: "#/components/schemas/OrganizationWebsite"
        members:
          type: "array"
          items:
            $ref: "#/components/schemas/UserListItem"
      required:
        - "id"
        - "name"
        - "displayName"
    MemberRole:
      type: "string"
      enum:
        - "VIEWER"
        - "CONTRIBUTOR"
        - "ADMIN"
      description: |
        The role of the user in the organization
        
        - `VIEWER`: The user can view and use all resources of the organization
        - `CONTRIBUTOR`: The user can create new resources for an organization, and becomes resource ADMIN
        - `ADMIN`: The user can manage members and all resources of an organization
    OrganizationMember:
      type: "object"
      description: "A member of an organization."
      properties:
        user:
          $ref: "#/components/schemas/User"
        role:
          $ref: "#/components/schemas/MemberRole"
    Visibility:
      type: "string"
      enum:
        - "PUBLIC"
        - "PRIVATE"
      description: |
        Indicates the visibility of the resource. 
        
        - `PUBLIC` resources are visible to all users.
        - `PRIVATE` resources are visible to the owner. And in case it is owned by an organization, also visible by all members of that organization.
    OrganizationInvite:
      type: "object"
      description: "An non-personalized time-boxed invite to join an organization."
      properties:
        token:
          type: "string"
          description: "The generated token, encrypting organization, expiration timestamp, and role (VIEW)."
        link:
          type: "string"
          description: "The generated invite link."
        expirationDate:
          type: "string"
          format: "date-time"
          description: "The expiration date of the invite link. 72 hours after creation."
        organizationId:
          $ref: "#/components/schemas/OrganizationId"
    OrganizationConfig:
      type: "object"
      description: "The configuration for creating a new organization."
      properties:
        name:
          $ref: "#/components/schemas/OrganizationName"
        displayName:
          $ref: "#/components/schemas/OrganizationDisplayName"
        description:
          $ref: "#/components/schemas/OrganizationDescription"
        logoBase64:
          $ref: "#/components/schemas/OrganizationLogoBase64"
        email:
          $ref: "#/components/schemas/OrganizationEmail"
        website:
          $ref: "#/components/schemas/OrganizationWebsite"
      required:
        - "name"
        - "displayName"
    OrganizationPatchConfig:
      type: "object"
      description: "The configuration for updating an organization."
      properties:
        name:
          $ref: "#/components/schemas/OrganizationName"
        displayName:
          $ref: "#/components/schemas/OrganizationDisplayName"
        description:
          $ref: "#/components/schemas/OrganizationDescription"
        logoBase64:
          $ref: "#/components/schemas/OrganizationLogoBase64"
        email:
          $ref: "#/components/schemas/OrganizationEmail"
        website:
          $ref: "#/components/schemas/OrganizationWebsite"
    MemberRolePatchConfig:
      type: "object"
      description: "The configuration for updating a member's role."
      properties:
        role:
          $ref: "#/components/schemas/MemberRole"
      required:
        - "role"

    # ACCOUNT
    AccountId:
      type: "string"
      description: "The unique identifier of an account (either a user or an organization)."
    AccountName:
      type: "string"
      description: "The name of an account (either a user or an organization)."
    AccountType:
      type: "string"
      enum:
        - "USER"
        - "ORGANIZATION"
    AccountImage:
      type: "string"
      description: "The URL of the account's image."

    # SYSTEM
    UsageReportPeriod:
      type: "object"
      description: "The usage report for a specific month"
      properties:
        periodStart:
          description: "The UTC date and time when the reported time period started"
          type: "string"
          format: "date-time"
        periodEnd:
          description: "The UTC date and time when the reported time period started"
          type: "string"
          format: "date-time"
        totalDatapoints:
          type: "integer"
          format: "int64"
          description: "The number of datapoints generated during the reported period"
        totalRows:
          type: "integer"
          format: "int64"
          description: "The number of rows generated during the reported period"
        totalCredits:
          type: "number"
          format: "double"
          description: "The number of credits used during the reported period"

    #####################
    ## mostlyai-engine ##
    #####################

    ModelType:
      type: "string"
      description: |
        The type of model.

        - `TABULAR`: A generative AI model tailored towards tabular data, trained from scratch.
        - `LANGUAGE`: A generative AI model build upon a (pre-trained) language model.
      enum:
        - "TABULAR"
        - "LANGUAGE"
    ModelEncodingType:
      type: "string"
      description: |
        The encoding type used for model training and data generation.
        
        - `AUTO`: Model chooses among available encoding types based on the column's data type.
        - `TABULAR_CATEGORICAL`: Model samples from existing (non-rare) categories.
        - `TABULAR_NUMERIC_AUTO`: Model chooses among 3 numeric encoding types based on the values.
        - `TABULAR_NUMERIC_DISCRETE`: Model samples from existing discrete numerical values.
        - `TABULAR_NUMERIC_BINNED`: Model samples from binned buckets, to then sample randomly within a bucket.
        - `TABULAR_NUMERIC_DIGIT`: Model samples each digit of a numerical value.
        - `TABULAR_CHARACTER`: Model samples each character of a string value.
        - `TABULAR_DATETIME`: Model samples each part of a datetime value.
        - `TABULAR_DATETIME_RELATIVE`: Model samples the relative difference between datetimes within a sequence.
        - `TABULAR_LAT_LONG`: Model samples a latitude-longitude column. The format is "latitude,longitude".
        - `LANGUAGE_TEXT`: Model will sample free text, using a LANGUAGE model.
        - `LANGUAGE_CATEGORICAL`: Model samples from existing (non-rare) categories, using a LANGUAGE model.
        - `LANGUAGE_NUMERIC`: Model samples from the valid numeric value range, using a LANGUAGE model.
        - `LANGUAGE_DATETIME`: Model samples from the valid datetime value range, using a LANGUAGE model.
      enum:
        - "AUTO"
        - "TABULAR_CATEGORICAL"
        - "TABULAR_NUMERIC_AUTO"
        - "TABULAR_NUMERIC_DISCRETE"
        - "TABULAR_NUMERIC_BINNED"
        - "TABULAR_NUMERIC_DIGIT"
        - "TABULAR_CHARACTER"
        - "TABULAR_DATETIME"
        - "TABULAR_DATETIME_RELATIVE"
        - "TABULAR_LAT_LONG"
        - "LANGUAGE_TEXT"
        - "LANGUAGE_CATEGORICAL"
        - "LANGUAGE_NUMERIC"
        - "LANGUAGE_DATETIME"
      default: "AUTO"
    RebalancingConfig:
      type: "object"
      description: "Configure rebalancing."
      properties:
        column:
          type: "string"
          description: |
            The name of the column to be rebalanced.  Only applicable for a subject table.
            Only applicable for categorical columns.
        probabilities:
          type: "object"
          description: |
            The target distribution of samples values.
            The keys are the categorical values, and the values are the probabilities.
          example:
            - US: 0.8
            - male: 0.5
              female: 0.5
          additionalProperties:
            type: "number"
            format: "double"
      required:
        - "column"
        - "probabilities"
    ImputationConfig:
      type: "object"
      description: "Configure imputation."
      properties:
        columns:
          description: |
            The names of the columns to be imputed.
            Imputed columns will suppress the sampling of NULL values.
          type: "array"
          items:
            type: "string"
      required:
        - "columns"
    FairnessConfig:
      type: "object"
      description: |
        Configure a fairness objective for the table. 
        Only applicable for a subject table.
        The generated synthetic data will maintain robust statistical parity between the target column and 
        the specified sensitive columns. All these columns must be categorical.
      properties:
        targetColumn:
          description: "The name of the target column."
          type: "string"
          minLength: 1
        sensitiveColumns:
          description: "The names of the sensitive columns."
          type: "array"
          items:
            type: "string"
      required:
        - "targetColumn"
        - "sensitiveColumns"
    DifferentialPrivacyConfig:
      type: "object"
      description: |
        The optional differential privacy configuration for training the model. 
        If not provided, then no differential privacy will be applied.
      properties:
        maxEpsilon:
          type: "number"
          format: "double"
          description: |
            Specifies the maximum allowable epsilon value. If the training process exceeds this threshold, it will be terminated early. Only model checkpoints with epsilon values below this limit will be retained. 
            If not provided, the training will proceed without early termination based on epsilon constraints.
          minimum: 0.0
          maximum: 10000.0
        noiseMultiplier:
          type: "number"
          format: "double"
          description: |
            The ratio of the standard deviation of the Gaussian noise to the L2-sensitivity of the function to which the noise is added (How much noise to add).
          default: 1.5
          minimum: 0.0
          maximum: 10000.0
        maxGradNorm:
          type: "number"
          format: "double"
          description: |
            The maximum norm of the per-sample gradients for training the model with differential privacy.
          default: 1.0
          minimum: 0.0
          maximum: 10000.0
        delta:
            type: "number"
            format: "double"
            description: |
              The delta value for differential privacy. It is the probability of the privacy guarantee not holding. 
              The smaller the delta, the more confident you can be that the privacy guarantee holds.
            default: 1e-5
            minimum: 0.0
            maximum: 1.0

    #################
    ## mostlyai-qa ##
    #################

    ModelMetrics:
      type: "object"
      description: |
        Metrics regarding the quality of synthetic data, measured in terms of accuracy, similarity, and distances.
        
        1. **Accuracy**: Metrics regarding the accuracy of synthetic data, measured as the closeness of discretized lower
        dimensional marginal distributions.
        2. **Similarity**: Metrics regarding the similarity of the full joint distributions of samples within an embedding
        space.
        3. **Distances**: Metrics regarding the nearest neighbor distances between training, holdout, and synthetic samples
        in an embedding space. Useful for assessing the novelty / privacy of synthetic data.
        
        The quality of synthetic data is assessed by comparing these metrics to the same metrics of a holdout dataset.
        The holdout dataset is a subset of the original training data, that was not used for training the synthetic data
        generator. The metrics of the synthetic data should be as close as possible to the metrics of the holdout data.
      properties:
        accuracy:
          $ref: "#/components/schemas/Accuracy"
        distances:
          $ref: "#/components/schemas/Distances"
        similarity:
          $ref: "#/components/schemas/Similarity"
    Accuracy:
      type: "object"
      description: |
        Metrics regarding the accuracy of synthetic data, measured as the closeness of discretized lower dimensional
        marginal distributions.
        
        1. **Univariate Accuracy**: The accuracy of the univariate distributions for all target columns.
        2. **Bivariate Accuracy**: The accuracy of all pair-wise distributions for target columns, as well as for target
        columns with respect to the context columns.
        3. **Coherence Accuracy**: The accuracy of the auto-correlation for all target columns.
        
        Accuracy is defined as 100% - [Total Variation Distance](https://en.wikipedia.org/wiki/Total_variation_distance_of_probability_measures) (TVD),
        whereas TVD is half the sum of the absolute differences of the relative frequencies of the corresponding
        distributions.
        
        These accuracies are calculated for all discretized univariate, and bivariate distributions. In case of sequential
        data, also for all coherence distributions. Overall metrics are then calculated as the average across these
        accuracies.
        
        All metrics can be compared against a theoretical maximum accuracy, which is calculated for a same-sized holdout.
        The accuracy metrics shall be as close as possible to the theoretical maximum, but not significantly higher, as
        this would indicate overfitting.
      properties:
        overall:
          description: |
            Overall accuracy of synthetic data, averaged across univariate, bivariate, and coherence.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        univariate:
          description: |
            Average accuracy of discretized univariate distributions.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        bivariate:
          description: |
            Average accuracy of discretized bivariate distributions.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        coherence:
          description: |
            Average accuracy of discretized coherence distributions. Only applicable for sequential data.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        overallMax:
          description: |
            Expected overall accuracy of a same-sized holdout. Serves as a reference for `overall`.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        univariateMax:
          description: |
            Expected univariate accuracy of a same-sized holdout. Serves as a reference for `univariate`.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        bivariateMax:
          description: |
            Expected bivariate accuracy of a same-sized holdout. Serves as a reference for `bivariate`.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        coherenceMax:
          description: |
            Expected coherence accuracy of a same-sized holdout. Serves as a reference for `coherence`.
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
    Similarity:
      type: "object"
      description: |
        Metrics regarding the similarity of the full joint distributions of samples within an embedding space.
        
        1. **Cosine Similarity**: The cosine similarity between the centroids of synthetic and training samples.
        2. **Discriminator AUC**: The AUC of a discriminative model to distinguish between synthetic and training samples.
        
        The SentenceTransformer model [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) is
        used to compute the embeddings of a string-ified representation of individual records. In case of sequential data
        the records, that belong to the same group, are being concatenated. We then calculate the cosine similarity
        between the centroids of the provided datasets within the embedding space.
        
        Again, we expect the similarity metrics to be as close as possible to 1, but not significantly higher than what is
        measured for the holdout data, as this would again indicate overfitting.
        
        In addition, a discriminative ML model is trained to distinguish between training and synthetic samples. The
        ability of this model to distinguish between training and synthetic samples is measured by the AUC score. For
        synthetic data to be considered realistic, the AUC score should be close to 0.5, which indicates that the synthetic
        data is indistinguishable from the training data.
      properties:
        cosineSimilarityTrainingSynthetic:
          description: "Cosine similarity between training and synthetic centroids."
          type: "number"
          format: "double"
          minimum: -1.0
          maximum: 1.0
        cosineSimilarityTrainingHoldout:
          description: "Cosine similarity between training and holdout centroids. Serves as a reference for `cosine_similarity_training_synthetic`."
          type: "number"
          format: "double"
          minimum: -1.0
          maximum: 1.0
        discriminatorAUCTrainingSynthetic:
          description: "Cross-validated AUC of a discriminative model to distinguish between training and synthetic samples."
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        discriminatorAUCTrainingHoldout:
          description: "Cross-validated AUC of a discriminative model to distinguish between training and holdout samples. Serves as a reference for `discriminator_auc_training_synthetic`."
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
    Distances:
      type: "object"
      description: |
        Metrics regarding the nearest neighbor distances between training, holdout, and synthetic samples in an embedding
        space. Useful for assessing the novelty / privacy of synthetic data.
        
        The provided data is first down-sampled, so that the number of samples match across all datasets. Note, that for
        an optimal sensitivity of this privacy assessment it is recommended to use a 50/50 split between training and
        holdout data, and then generate synthetic data of the same size.
        
        The embeddings of these samples are then computed, and the L2 nearest neighbor distances are calculated for each
        synthetic sample to the training and holdout samples. Based on these nearest neighbor distances the following
        metrics are calculated:
          - Identical Match Share (IMS): The share of synthetic samples that are identical to a training or holdout sample.
          - Distance to Closest Record (DCR): The average distance of synthetic to training or holdout samples.
        
        For privacy-safe synthetic data we expect to see about as many identical matches, and about the same distances
        for synthetic samples to training, as we see for synthetic samples to holdout.
      properties:
        imsTraining:
          description: "Share of synthetic samples that are identical to a training sample."
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        imsHoldout:
          description: "Share of synthetic samples that are identical to a holdout sample. Serves as a reference for `ims_training`."
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0
        dcrTraining:
          description: "Average L2 nearest-neighbor distance between synthetic and training samples."
          type: "number"
          format: "double"
          minimum: 0.0
        dcrHoldout:
          description: "Average L2 nearest-neighbor distance between synthetic and holdout samples. Serves as a reference for `dcr_training`."
          type: "number"
          format: "double"
          minimum: 0.0
        dcrShare:
          description: "Share of synthetic samples that are closer to a training sample than to a holdout sample. This should not be significantly larger than 50%."
          type: "number"
          format: "double"
          minimum: 0.0
          maximum: 1.0

security:
  - ApiKeyAuth: [ ]

servers:
  - url: https://app.mostly.ai/api/v2