Alchemite API
API docs by Redocly

Alchemite (0.91.0)

Download OpenAPI specification:

Datasets

Uploading and downloading datasets for training.

Upload or start uploading a dataset

Create a dataset for a model to train on and return the dataset ID. If the 'data' parameter is not given in the JSON request body then it will be assumed that the data is to be uploaded later in chunks. In this case the parameter 'status' in the dataset metadata will be set to 'uploading'. If 'data' is provided, the 'status' will be set to 'pending' while the dataset is ingested into the datastore. When finished, the final 'status' the dataset enters will be 'uploaded'. Datasets with more than 10,000 columns are not currently supported and cannot be uploaded.

Authorizations:
oauth
Request Body schema: application/json
name
required
string
tags
Array of strings unique

Optional tags to attach to the dataset

notes
string

An optional free field for notes about the model

revisesId
string

The UUID of the dataset this revisesId (its parent).

rowCount
required
integer

The number of rows in the array, not including column headers.

columnHeaders
required
Array of strings

List of all column headers in the order they appear in the dataset.

initialColumnHeaders
Array of strings

List of initial column headers, before extensions and calculatedColumns are applied.

Array of objects or null (CategoricalColumn)

The possible categorical values for each categorical column. There cannot be more than 1023 unique categorical values per column, and each value cannot be longer than 128 characters. Categorical values can be wrapped in speech marks (") in the csv to represent more complex strings containing special characters (i.e. commas), but speech marks are not allowed to appear anywhere apart from the beginning and end of a value. Quoted categorical values cannot be used in vector categorical columns. Quoted categoricals will be reduced to a form without explicit speech marks where possible, e.g. the values of "red" and red will be treated as identical. Categorical values cannot consist of purely whitespace and cannot contain semicolons. Leading/trailing whitespace around a categorical cell will be trimmed away, although surrounding whitespace enclosed within speech marks will be preserved. Categorical values also cannot be words reserved for special numerical types, such as NaN, +NaN, -NaN and further variations. Categorical integers are deprecated, please use string values instead.

Array of objects or null (OrdinalColumn)

The possible ordinal values for each ordinal column.

descriptorColumns
required
Array of integers
Items Enum: 0 1

List of length equal to the number of columns where each element is 1 or 0. A value of 1 denotes that the corresponding column is a descriptor column. A descriptor column is an input-only column whose values will not need to be predicted.

autoDetectCompleteColumns
boolean
Default: false

Whether to automatically tag descriptors in the dataset with no missing values as completeColumns or not. If set to 'true', then completeColumns cannot be specified.

completeColumns
Array of integers
Items Enum: 0 1

List of length equal to the number of columns where each element is 1 or 0. A value of 1 denotes that the corresponding column is a "complete column". This means the column must have no missing values in the dataset. It is also recommended to not ask a model trained on this dataset to make predictions with missing values in a "complete column". All "complete columns" must be descriptor columns as well. Marking columns as "complete columns" can significantly speed up model training. If completeColumns is not given then none of the columns will be marked as "complete columns". If given, autoDetectCompleteColumns must be set to 'false'.

Array of objects non-empty unique

Additional columns to be added to the dataset using an closed-form expression of other columns. They will be calculated for each row before being passed to Alchemite for training or predicting values. If any columns referenced in the expression are missing, the value of the calculated column in that row will also be missing. Each calculated column's expression may only reference columns in the original dataset, or those defined earlier in the list. The column name must not already appear in the dataset. No referenced column may be categorical. Each new column will be a non-complete descriptor column, unless all referenced columns are complete, when it will be a complete descriptor column. If present, calculated columns will be inserted as the last columns of the dataset.

measurementGroups
Array of integers or null[ items >= 1 ]

A "measurement group" is a group of columns that are usually measured at the same time. So when making predictions for one of these columns it is expected that the other columns in the measurement group will not be present. The measurementGroups argument can be specified to avoid training a model that relies on values in a measurement group to predict other values in the same group.

measurementGroups is a list of length equal to the number columns in the training dataset specifying which measurement group (denoted by in integer) each column belongs to. The order of measurementGroups must correspond to the training dataset's 'columnHeaders' parameter. Descriptor columns should be included in measurementGroups but they will always be used, regardless of the measurement group they are in.

For example, if measurementGroups=[1,2,3,1] then the first and last columns are expected to be known simultaneously and so are in the same measurement group, while the second and third columns may be known or unknown regardless of the knowledge of other columns and so are in their own measurement groups.

If measurementGroups is not provided then it is assumed that every column is in its own measurement group.

data
string

The CSV specification we conform to can be found at https://www.rfc-editor.org/rfc/rfc4180. A string in CSV format corresponding to a 2D array with row and column headers. Row and column headers must be unique. Row and column headers containing leading/trailing whitespace will not be trimmed and will be interpreted as they appear in the data. Categorical and vector values are defined outside of the set specification, although rules for their implementation can be found under their respective sections.

Sets of 2D vectors can be included by mapping each axis to a column and separating the values corresponding to each vector with a semicolon. If these vectors are used in the dataset then the columns which are paired as vectors must be provided in the 'vectorPairs' argument as part of the POST request.

In the example below the 'time' and 'temperature' columns are paired as vectors so in the first line their values map to the vectors (0,10), (1,28), (2,35), (4,42).

, heat applied, time , temperature A, 30 , 0;1;2;4, 10;28;35;42 B, 10 , 0;5 , 10;18

vectorPairs
Array of strings or null non-empty unique [ items = 2 items ]
Deprecated

A list of pairs of column names. The columns in each pair are the axes for a 2D coordinate system. Deprecated, it is recommended that series-based data is split out over separate columns for each series point.

Array of ExtensionInfocol (object) or Extension (object)

Specify preprocessing methods to be ran on the dataset before it is uploaded. For any Alchemite methods that require new data being provided, the required data for the extension must be present to ensure the preprocessing can be done on the new data to match the dataset. Alchemite can then use any generated data from the preprocessing step to make more informed predictions. Use of extensions requires the equivalent alchemiteapi.extensions. scope. This feature is experimental and any existing extensions are subject to breaking changes. If you would like access to extensions please contact Intellegens at support@intellegens.com

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "revisesId": "00112233-4455-6677-8899-aabbccddeeff",
  • "rowCount": 0,
  • "columnHeaders": [
    ],
  • "initialColumnHeaders": [
    ],
  • "categoricalColumns": [
    ],
  • "ordinalColumns": [
    ],
  • "descriptorColumns": [
    ],
  • "autoDetectCompleteColumns": false,
  • "completeColumns": [
    ],
  • "calculatedColumns": [
    ],
  • "measurementGroups": [
    ],
  • "data": ",C,Ni,Si,Young's modulus,Resistivity\nCarbon steel 1,0.105,0,0,209.9,14.4\nCarbon steel 2,0.2,,0,,17\nLow alloy steel,,0,0.25,206.4,22.40\n",
  • "vectorPairs": [
    ],
  • "extensions": [
    ]
}

Response samples

Content type
application/json
{}

List the metadata for every dataset

Authorizations:
oauth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List sorted and filtered dataset metadata

Returns all datasets matching the query passed.

Authorizations:
oauth
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 100 ]
Default: 20

The number of items to return.

Request Body schema: application/json
Array of objects = 1 items

Sort the result by the dataset's attributes.

object non-empty

Filter datasets based on their attributes. Note that currently each filter is AND'ed.

Responses

Request samples

Content type
application/json
{
  • "sort": [
    ],
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "total": 0,
  • "result": [
    ]
}

Get a dataset's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
{
  • "id": "00112233-4455-6677-8899-aabbccddeeff",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "status": "uploading",
  • "detail": "string",
  • "revisesId": "00112233-4455-6677-8899-aabbccddeeff",
  • "revisionIds": [
    ],
  • "rowCount": 0,
  • "columnCount": 0,
  • "columnHeaders": [
    ],
  • "initialColumnHeaders": [
    ],
  • "categoricalColumns": [
    ],
  • "ordinalColumns": [
    ],
  • "columnInfo": [
    ],
  • "descriptorColumns": [
    ],
  • "completeColumns": [
    ],
  • "measurementGroups": [
    ],
  • "columnFractionDataPresent": [
    ],
  • "vectorPairs": [
    ],
  • "modelCount": 0,
  • "createdAt": 0,
  • "sharedThrough": [
    ],
  • "sharing": {
    },
  • "extensions": [
    ]
}

Update a dataset's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the dataset. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the dataset

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Delete a dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
{}

List the metadata for every chunk of a dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Restart uploading a dataset

Delete all the chunks associated with this dataset upload

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
{}

Upload a chunk of a dataset's rows

Upload a subset of rows from the full dataset as a CSV file with row and column headers. If a chunk with this chunkNumber already exists then replace it.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

chunk_number
required
integer

An integer which identifies this chunk of data

Request Body schema: text/csv
string <binary> (ChunkCSVData)

A file in CSV format corresponding to a 2D array with row and column headers. The column headers must be the same as the columnHeaders list provided for "POST /datasets" or "POST /models/{id}/dataset" and in the same order.

Responses

Response samples

Content type
application/json
{}

Get a chunk's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

chunk_number
required
integer

An integer which identifies this chunk of data

Responses

Response samples

Content type
application/json
{
  • "chunkNumber": 0,
  • "rowCount": 0,
  • "columnCount": 0,
  • "createdAt": 0,
  • "status": "uploading",
  • "detail": "string"
}

Delete a chunk

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

chunk_number
required
integer

An integer which identifies this chunk of data

Responses

Response samples

Content type
application/json
{}

Finish uploading a dataset

Collate all the uploaded chunks into the final dataset. This will set the status of the dataset to 'uploaded'.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
{}

Download a dataset

Download the dataset as a CSV file. The columns may not be in the same order as they were given at upload. If the dataset uses extensions then this csv will have all columns that appeared during the extension (eg if a column was removed and another added, then the CSV will contain both).

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
{}

Share dataset with a group

Add a group to a dataset which allows all users belonging to that group to have access to the dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Stop sharing dataset with group

Delete group from dataset's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Get groups with which dataset is shared

Get dataset's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Reduce the dimensionality of a dataset

Reduce the dimensionality of a dataset down to a specified number of dimensions through PCA or UMAP. The dataset being reduced must have at least 5 rows and at most 50,000 rows. There must also be fewer than 10,000 columns and fewer than 5,000,000 cells overall. Vector columns are not supported and will be ignored during reduction.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
required
Model-based Reduction Body (object) or Model-based Reduction Body for multiple Data Types (object) or Dataset-based Reduction Body (object) or Dataset-based Reduction Body for multiple Data Types (object)

Information regarding the data to be reduced.

required
PCA Reduction Body (object) or UMAP Reduction Body (object) or Auto UMAP Reduction Body (object)

The method of dimensionality reduction and the appropriate parameters.

Responses

Request samples

Content type
application/json
{
  • "reductionData": {
    },
  • "reductionMethod": {
    }
}

Response samples

Content type
application/json
{
  • "reductionCoordinates": {
    },
  • "reductionMetadata": {
    }
}

Get all calculated column expressions for a given dataset

Get all calculated column expressions for a given dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get all column groups for a given dataset

Get all column groups for a given dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a new column group for a dataset

Create a new column group for a dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
required
name
required
string non-empty

Name of the column group. Must be unique

columns
required
Array of strings unique

List of the columns in the column group

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "columns": [
    ]
}

Response samples

Content type
application/json
{}

Create multiple new column groups for a dataset

Create multiple new column groups for a dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
required
required
Array of objects (Request object for column groups) non-empty

Responses

Request samples

Content type
application/json
{
  • "columnGroups": [
    ]
}

Response samples

Content type
application/json
{}

Get specific column group for a given dataset

Get specific column group for a given dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

column_group_id
required
string <uuid>

Unique ID of the column group

Responses

Response samples

Content type
application/json
{
  • "id": "00112233-4455-6677-8899-aabbccddeeff",
  • "name": "Ingredient Set 1",
  • "columns": [
    ]
}

Update a column group

Update a column group

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

column_group_id
required
string <uuid>

Unique ID of the column group

Request Body schema: application/json
name
string non-empty

New name of the column group. Will replace the previous name. Must be unique

columns
Array of strings unique

List of the new columns in the column group. Will replace the previous column list for the group

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "columns": [
    ]
}

Response samples

Content type
application/json
{}

Delete a column group

Delete a column group

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

column_group_id
required
string <uuid>

Unique ID of the column group

Responses

Response samples

Content type
application/json
{}

Returns histograms for provided columns

Returns histograms for provided columns

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the dataset.

Request Body schema: application/json
minBins
integer [ 1 .. 200 ]
Default: 1

The mininum number of bins to return. Must be equal to or below 'max_bins'.

maxBins
integer [ 1 .. 200 ]
Default: 30

The maxinum number of bins to return. Must be equal to or above 'min_bins'.

columns
Array of strings non-empty

The columns to return the histogram for. If not given, will return the histogram for all columns.

Responses

Request samples

Content type
application/json
{
  • "minBins": 1,
  • "maxBins": 100,
  • "columns": [
    ]
}

Response samples

Content type
application/json
{
  • "Continuous Column": {
    },
  • "Categorical Column": {
    },
  • "Empty Column": null
}

Creates a favourited dataset

Create new reference to a favourite dataset

Authorizations:
oauth
Request Body schema: application/json
datasetID
required
string <uuid>

The ID of the dataset being marked as a favourite

modelID
required
string <uuid>

The ID of the model the saved dataset relates to

Responses

Request samples

Content type
application/json
{
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "modelID": "17448b37-e359-404a-84aa-35f10765ba44"
}

Response samples

Content type
application/json
{}

Get all datasets marked as favourited

Returns specified datasets marked as favourited

Authorizations:
oauth
Request Body schema: application/json
object non-empty

Filter favourite datasets based on model attributes.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Gets dataset from favourites

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the favourite resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "modelID": "17448b37-e359-404a-84aa-35f10765ba44"
}

Removes dataset from favourites

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the favourite resource.

Responses

Response samples

Content type
application/json
{}

Model dataset

Uploading and downloading the dataset associated with a particular model.

Get the metadata of a model's training dataset

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{
  • "id": "00112233-4455-6677-8899-aabbccddeeff",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "status": "uploading",
  • "detail": "string",
  • "revisesId": "00112233-4455-6677-8899-aabbccddeeff",
  • "revisionIds": [
    ],
  • "rowCount": 0,
  • "columnCount": 0,
  • "columnHeaders": [
    ],
  • "initialColumnHeaders": [
    ],
  • "categoricalColumns": [
    ],
  • "ordinalColumns": [
    ],
  • "columnInfo": [
    ],
  • "descriptorColumns": [
    ],
  • "completeColumns": [
    ],
  • "measurementGroups": [
    ],
  • "columnFractionDataPresent": [
    ],
  • "vectorPairs": [
    ],
  • "modelCount": 0,
  • "createdAt": 0,
  • "sharedThrough": [
    ],
  • "sharing": {
    },
  • "extensions": [
    ]
}

Download a dataset

Download the dataset as a CSV file. The columns may not be in the same order as they were given at upload.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Models

Creating, training and using a model.

Define a model to be trained

Create new model and return the model ID associated with it.

Authorizations:
oauth
Request Body schema: application/json
required

A JSON object containing the name and training method for the model. The dataset ID of the dataset that will be used to train the model must be provided under the key trainingDatasetId.

name
required
string
tags
Array of strings unique

Optional tags to attach to the model

notes
string

An optional free field for notes about the dataset

projectId
string <uuid>

The project this model belongs to. The user must have permission to see the respective project to set this value

status
string (ModelStatus)
Enum: "new" "optimizing hyperparameters" "training" "trained" "failed" "pending"

Status of the model

revisesId
string

The UUID of the model this revisesID (its parent).

trainingMethod
required
string
Value: "alchemite"

The method used to train the model.

trainingDatasetId
string <uuid>

ID of the dataset used to train the model.

validationMethod
string (ModelValidationMethods)
Enum: "none" "80/20" "5-fold" "custom"

Validation method for the model

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff",
  • "status": "new",
  • "revisesId": "00112233-4455-6677-8899-aabbccddeeff",
  • "trainingMethod": "alchemite",
  • "trainingDatasetId": "00112233-4455-6677-8899-aabbccddeeff",
  • "validationMethod": "none"
}

Response samples

Content type
application/json
{}

List the metadata for every model

Authorizations:
oauth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List sorted and filtered model metadata

Returns all models matching the query passed.

Authorizations:
oauth
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 100 ]
Default: 20

The number of items to return.

Request Body schema: application/json
Array of objects = 1 items

Sort the result by the model attributes.

object non-empty

Filter models based on model attributes. Note that currently each filter is AND'ed.

Responses

Request samples

Content type
application/json
{
  • "sort": [
    ],
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "total": 0,
  • "result": [
    ]
}

Get a model's metadata

Get the metadata for the model. This includes, for example, ID, name, status and percentage training completion.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{
  • "id": "00112233-4455-6677-8899-aabbccddeeff",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff",
  • "status": "new",
  • "revisesId": "00112233-4455-6677-8899-aabbccddeeff",
  • "revisionIds": [
    ],
  • "trainingMethod": "alchemite",
  • "trainingMethodVersion": "20180817",
  • "trainingDatasetId": "00112233-4455-6677-8899-aabbccddeeff",
  • "trainingStartTime": 0,
  • "trainingCompletionTime": 0,
  • "trainingProgress": 100,
  • "hyperparameterOptimizationMethod": "none",
  • "bespokeColumnHyperparameters": true,
  • "hyperparameterOptimizationStartTime": 0,
  • "hyperparameterOptimizationCompletionTime": 0,
  • "hyperparameterOptimizationProgress": 100,
  • "trainingRealTime": 0,
  • "trainingCPUTime": 0,
  • "trainingPeakMemoryUsage": 0,
  • "trainingHyperparameters": { },
  • "trainingColumnHeaders": [
    ],
  • "trainingInitialColumnHeaders": [
    ],
  • "trainingColumnInfo": [
    ],
  • "categoricalColumns": [
    ],
  • "ordinalColumns": [
    ],
  • "fileSize": 0,
  • "validationMethod": "none",
  • "validationMetric": 1,
  • "validationRSquared": 1,
  • "validationTargetColumns": [
    ],
  • "loaded": true,
  • "estimatedModelMemory": 0,
  • "virtualTraining": true,
  • "permittedColumnRelationships": [
    ],
  • "hyperoptSampleRequest": 0,
  • "virtualExperimentValidation": true,
  • "trainingDatasetOutliersJobId": "3a2dfb4f-1a3f-4d86-86c2-bfd7491a36b4",
  • "trainingDatasetOutliersJobStatus": "pending",
  • "createdAt": 0,
  • "sharedThrough": [
    ],
  • "sharing": {
    },
  • "detail": "string"
}

Update a model's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the model. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the model

projectId
string or null <uuid>

The project this model belongs to. The user must have permission to see the respective project to set this value. Set to null to remove from current project.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff"
}

Response samples

Content type
application/json
{}

Delete a model

Delete the model and stop any in progress training

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Get a model's validation splits.

Get the validation splits used for a model. Requires that the model has been trained, and was not trained with validation set to 'none'.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{
  • "validationSplits": [
    ]
}

Copy a model

Create a copy of the model which is identical except for having a new model ID. The model ID of the copy will be returned in the response.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Import a model

Upload a zip file, as provided by GET /models/{id}/download, which will set the data and metadata of a new model. If the model ID included in the provided metadata is not already assigned to another model then it will be used as the ID for the new model, otherwise a new unique ID will be created for the new model. In either case a successful response will return the model ID of the new model.

Not enabled by default. Please contact Intellegens if required

Authorizations:
oauth
Request Body schema: application/zip
string <binary>

A .zip file containing the model data and metadata, as provided by GET /models/{id}/download.

Responses

Response samples

Content type
application/json
{}

Export a model

Download the model data and metadata as a zip file

Not enabled by default. Please contact Intellegens if required

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Train a model

Train the model on the dataset corresponding to the 'trainingDatasetId' parameter in the model metadata. The dataset must have the status 'processing' or 'uploaded' to begin to have a model trained on it.

If hyperparameterOptimization is 'none' then the model 'status' will be first set to 'pending' and then 'training' once the model has started training. Otherwise the model 'status' will be first set to 'optimizing hyperparameters' and then once the optimal hyperparameters have been found set to 'pending' and then 'training'. The model status will be set to 'trained' once it has finished training and is ready to use. Use GET /model/{id} to get model status as well as percentage training and hyperparameter optimization completion.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
validation
string
Default: "none"
Enum: "none" "80/20" "5-fold" "custom"

Methods for validating the model using the provided dataset. If set to "custom", validationSplits must also be provided

validationTargetColumns
Array of strings or null non-empty unique

A list of the training dataset's column names that the model's validation metric will be the median average over. Cannot include descriptor columns. If not provided then the model's validation metric will be the median average over all non-descriptor columns.

Array of objects (Validation Split) [ 1 .. 10 ] items unique

A list of test-train pairs, describing the row IDs of the training dataset to include in each validation split. Must be provided exactly when validation is 'custom'.

hyperparameterOptimization
string
Default: "none"
Enum: "none" "random" "TPE"

Search method for finding the optimal parameters to use when training the model. If 'none' then the parameters as specified by the 'hyperparameters' argument will be used to train the model. If 'hyperparameterOptimization' is not 'none' then 'validation' must also be not 'none'.

bespokeColumnHyperparameters
boolean
Default: true

Whether to use bespoke hyperparameters for each target column. If false, hyperparameters are shared between columns. Defaults to true.

hyperparameters
object

The hyperparameters which Alchemite will use when training. If 'hyperparameterOptimization' is 'none', these hyperparameters will be used for training, otherwise the hyperparameters will be used as a starting point for optimization. If no argument is provided for this parameter and the model was previously trained then the existing hyperparameters will be used to train the model, otherwise Alchemite's default hyperparameters will be used instead.

fractionDataPresent
Array of numbers[ items [ 0 .. 1 ] ]

The fraction of data expected to be in each column of the datasets which the model will make predictions from. The list 'fractionDataPresent' should be ordered corresponding to the training dataset's 'columnHeaders' parameter.

virtualExperimentValidation
boolean
Default: false

If true then only the descriptor columns will be used to make predictions when computing the validation metric.

virtualTraining
boolean
Default: false

If true then only the descriptor columns will be used as input in the first iteration of training

Array of objects non-empty unique

An array of objects defining which columns the ML model is able to use or not use as inputs when modelling specific columns.

The "allow" and "disallow" arrays must contain distinct columns. They do not need to contain all columns in the dataset.

If columns are not allowed in either "allow" nor "disallow", the model will use default behaviors:

  • use all descriptors for all targets when virtualTraining is true.
  • use all descriptors + targets when virtualTraining is false for all targets (except for the same target -> target).

if virtualTraining is false: This is equivalent to passing "allow": list_of_all_columns for every column in the dataset. Therefore, passing allow when virtualTraining is false has no effect on the model. However, columns passed within "disallow" will have an effect.

if virtualTraining is true: This is equivalent to passing "allow": list_of_all_descriptors and passing "disallow" for all non descriptors. Therefore, passing descriptor columns in the "allow" list has no effect on the model. Similarly, passing non descriptor columns in the "disallow" list has no effect on the model. However, columns passed within "allow" for non descriptors, and "disallow" for descriptors will have an effect.

Interaction with Measurement Groups: If measurement groups are specified for the training dataset that are incompatible, a 400 response is returned. This happens when a column defined in "name" and one or more columns defined in "allow" are part of the same measurement group.

enableTrainingDatasetOutliers
boolean or null
Default: null

If true then compute the outliers in the training dataset using the validation sub-models. If validation is '5-fold', each will be trained on 80% of the full dataset to identify the outliers in the remaining 20%. If validation is 'custom', each row in a test set will be checked against a model trained on the matching train set. Please note, if validation is '80/20', only the validation 20% will report outliers, and is thus not recommended.

If null then will be set to true if validation is not equal to 'none'. Otherwise will be false.

Once trainingDatasetOutliersJobStatus in the model metadata has the value 'done' then the results will be available via /models/id/training-dataset-outliers. Computing the outliers this way is generally expected to give better results than using the model trained on the full dataset to identify the outliers in its own training dataset.

maxNumberSamples
integer [ 1 .. 2000 ]
Default: 300

The maximum number of hyperparameter optimization samples to use for training the model. Training may stop before the specified amount of samples if an ideal set of hyperparameters if found early. If 'hyperparameterOptimization' is 'none' then 'maxNumberSamples' will be ignored.

Responses

Request samples

Content type
application/json
{
  • "validation": "none",
  • "validationTargetColumns": [
    ],
  • "validationSplits": [
    ],
  • "hyperparameterOptimization": "none",
  • "bespokeColumnHyperparameters": true,
  • "hyperparameters": { },
  • "fractionDataPresent": [
    ],
  • "virtualExperimentValidation": false,
  • "virtualTraining": false,
  • "permittedColumnRelationships": [
    ],
  • "enableTrainingDatasetOutliers": null,
  • "maxNumberSamples": 300
}

Response samples

Content type
application/json
{}

Load model into memory

Load the model into memory so that future "/models/{id}/impute" requests will be faster. The "loaded" property in the model metadata shows whether the model is currently loaded or not. The model will be removed from memory if "timeout" seconds have passed since the model was loaded into memory and the model has not been used for "timeout" seconds. Calling the "/models/{id}/load" endpoint for an already loaded model will reset the timeout.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
timeout
integer
Default: 60

The number of seconds the model should wait in memory without receiving a request before being unloaded from memory.

Responses

Request samples

Content type
application/json
{
  • "timeout": 60
}

Response samples

Content type
application/json
{}

Unload model from memory

Remove a loaded model from memory. Impute requests can still be sent but the model will be loaded into memory at request time.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Importance of each column to each other column

Generate a global analysis of how important each input is for predicting each output.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
outputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as rows in the CSV response. If not given then all the columns in the training dataset will be included in the order of the model's trainingColumnHeaders property.

inputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as columns in the CSV response. If not given then all the columns in the training dataset will be included in the order of the model's trainingColumnHeaders property.

useOnlyDescriptors
boolean
Default: false

A boolean flag that will return the importance values considering only descriptor-to-target relationships if set to true. Otherwise, target-to-target importance will also be considered.

Responses

Request samples

Content type
application/json
{
  • "outputColumns": [
    ],
  • "inputColumns": [
    ],
  • "useOnlyDescriptors": false
}

Response samples

Content type
application/json
{}

Impute missing data

Given an incomplete dataset return the predictions for the missing values together with the corresponding uncertainties or full probability distribution for each prediction.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
returnProbabilityDistribution
boolean
Default: false

If true then the full probability distribution for each prediction will be returned, if false then the predicted value and uncertainty derived from that distribution will be returned instead.

datasetID
string <uuid>

The ID of a dataset to impute. The dataset must have the same column headers as the model's training dataset. Only one of 'datasetID' and 'data' should be provided.

returnRowHeaders
boolean
Default: false

If true then row headers will be returned in the response csv. If true and the 'data' property is given then it is required that the first column of csv data are unique row headers.

returnColumnHeaders
boolean
Default: false

If true then column headers will be returned in the response csv.

data
string

An array of CSV data with column headers. Only one of 'datasetID' and 'data' should be provided. If returnRowHeaders is true then the first column of the CSV should contain the unique row headers which identify each row.

Responses

Request samples

Content type
application/json
{
  • "returnProbabilityDistribution": false,
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "returnRowHeaders": false,
  • "returnColumnHeaders": false,
  • "data": "x,y,x+y,x-y\n1,0.2,,0.8\n0.5,0.3,,\n"
}

Response samples

Content type
application/json
{}

Request the influence model inputs have on a given output

Request the influence model inputs have on a given output. These influence values are calculated using the rows of the training dataset, representing how much of the output each input is responsible for.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
outputColumn
required
string

The output column to retrieve the influence for

Responses

Request samples

Content type
application/json
{
  • "outputColumn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "values": {
    }
}

Analyse predictions against given data

Analyse the model's predictions against a given dataset and, optionally, return the predictions themselves

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
One of
datasetID
required
string <uuid>

The ID of a dataset to use to make predictions. The dataset must have the same column headers as the model's training dataset. Only one of 'datasetID' and 'data' should be provided.

returnPredictions
boolean
Default: true

If true then the predicted values will be included in the response. If false only the analysis of those predictions will be returned

returnColumnHeaders
boolean
Default: false

If true then the predicted values, if returned, will include column headers on the first row.

virtualExperimentValidation
boolean
Default: false

If true then only the values in descriptor columns will be used to make predictions

Responses

Request samples

Content type
application/json
Example
{
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "returnPredictions": true,
  • "returnColumnHeaders": false,
  • "virtualExperimentValidation": false
}

Response samples

Content type
application/json
{
  • "meanValidationMetric": 1,
  • "meanValidationMetricUncertainty": 0,
  • "medianValidationMetric": 1,
  • "medianValidationMetricUncertainty": 0,
  • "meanCoefficientOfDetermination": 1,
  • "meanCoefficientOfDeterminationUncertainty": 0,
  • "medianCoefficientOfDetermination": 1,
  • "medianCoefficientOfDeterminationUncertainty": 0,
  • "meanRMSE": 0,
  • "meanRMSEUncertainty": 0,
  • "medianRMSE": 0,
  • "medianRMSEUncertainty": 0,
  • "totalUncertaintyDivergence": 0,
  • "columnAnalytics": [
    ],
  • "predictions": "A,1.0000,.2000,,.8000,.9333,.1000,,.8333,.0943,.0816,,.1247\nB,.5000,.3000,,,.5600,.6000,,,.1840,.2828,,\n"
}

Validate given data

Given a dataset return the predictions for the given values in the dataset with the uncertainties or full probability distribution for each prediction.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
returnProbabilityDistribution
boolean
Default: false

If true then the full probability distribution for each prediction will be returned, if false then the predicted value and uncertainty derived from that distribution will be returned instead.

datasetID
string <uuid>

The ID of a dataset to use to make predictions. The dataset must have the same column headers as the model's training dataset. Only one of 'datasetID' and 'data' should be provided.

returnRowHeaders
boolean
Default: false

If true then row headers will be returned in the response csv. If true and the 'data' property is given then it is required that the first column of csv data are row headers.

returnColumnHeaders
boolean
Default: false

If true then column headers will be returned in the response csv.

data
string

An array of CSV data with column headers. Only one of 'datasetID' and 'data' should be provided. If returnRowHeaders is true then the first column of the CSV should contain the unique row headers which identify each row.

Responses

Request samples

Content type
application/json
{
  • "returnProbabilityDistribution": false,
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "returnRowHeaders": false,
  • "returnColumnHeaders": false,
  • "data": "x,y,x+y,x-y\n1,0.2,,0.8\n0.5,0.3,,\n"
}

Response samples

Content type
application/json
{}

Predict given and missing data

Given a dataset return the predictions for all given and missing values in the dataset with the uncertainties or full probability distribution for each prediction.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
returnProbabilityDistribution
boolean
Default: false

If true then the full probability distribution for each prediction will be returned, if false then the predicted value and uncertainty derived from that distribution will be returned instead.

datasetID
string <uuid>

The ID of a dataset to use to make predictions. The dataset must have the same column headers as the model's training dataset. Only one of 'datasetID' and 'data' should be provided.

returnRowHeaders
boolean
Default: false

If true then row headers will be returned as the first column in the response csv. If true and the 'data' property is given then it is required that the first column of csv data are row headers.

returnColumnHeaders
boolean
Default: false

If true then column headers will be returned in the response csv.

data
string

An array of CSV data with column headers. Only one of 'datasetID' and 'data' should be provided. If returnRowHeaders is true then the first column of the CSV should contain the unique row headers which identify each row.

Responses

Request samples

Content type
application/json
{
  • "returnProbabilityDistribution": false,
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "returnRowHeaders": false,
  • "returnColumnHeaders": false,
  • "data": "x,y,x+y,x-y\n1,0.2,,0.8\n0.5,0.3,,\n"
}

Response samples

Content type
application/json
{}

Calculate the trendline between two columns

Given an input column and an output column from the model, a trendline of a specified amount of bins will be calculated. When a calculated or extension column is used as input, the underlying calculations do not alter the source columns and may not fully reflect the actual trend

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
inputColumn
string

Name of the input column for the trendline calculation. This column can be either a model descriptor or non-descriptor

outputColumn
string

Name of the output column for the trendline calculation. This column must be a model non-descriptor

binCount
integer [ 3 .. 20 ]
Default: 10

The number of splits in the trendline to calculate between the two columns

Responses

Request samples

Content type
application/json
{
  • "inputColumn": "string",
  • "outputColumn": "string",
  • "binCount": 10
}

Response samples

Content type
application/json
{
  • "x": [
    ],
  • "y": [
    ],
  • "uncertainties": [
    ]
}

Calculate the interaction between two columns with respect to an output column

Given two columns and an output column from the model, an interaction for a specified amount of bins will be calculated When a calculated or extension column is used as input(s), the underlying calculations do not alter the source columns and may not fully reflect the actual trend

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
inputColumns
Array of strings = 2 items

Name two columns to calculate the interaction with respect to. These columns can be either a model descriptor or non-descriptor

outputColumn
string

Name of the output column for the interaction calculation. This column must be a model non-descriptor

binCount
integer [ 3 .. 100 ]
Default: 10

The number of splits in the trendline to calculate between the two columns

Responses

Request samples

Content type
application/json
{
  • "inputColumns": [
    ],
  • "outputColumn": "string",
  • "binCount": 10
}

Response samples

Content type
application/json
{}

Get the result of an interaction request from a given job ID

Gets the result of an interaction request from a given job ID, where the request was made using post /models/{id}/prediction/interaction. If the job was successful, the interaction between two columns and a target output column will be returned

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
Example
{
  • "status": "failed",
  • "detail": "string"
}

Find the outlying values in a dataset

Compares a given array of data (complete or incomplete) with the corresponding predicted values. If a given value lies outside of the error bounds of the corresponding predicted value then it is deemed an outlier. Returns the given value of all outliers along with the corresponding predicted values, the number of standard deviations between the given and predicted values and the row and column indices of the outlier. If the outlier is part of a vector then the "Component Index" indicates which component of the vector is an outlier. If the outlier is not a vector then the "Component Index" will be 1.

If the outliers in the model's own training dataset are required then consider using /models/{id}/training-dataset-outliers instead

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
datasetID
string <uuid>

The ID of a dataset to check for outliers. The dataset must have the same column headers as the model's training dataset. Only one of 'datasetID' and 'data' should be provided.

data
string

An array of CSV data with column headers. Only one of 'datasetID' and 'data' should be provided.

outlierTolerance
number >= 0
Default: 1

How many standard deviations from a prediction results in a value being classified as an outlier.

returnRowHeaders
boolean
Default: false

If true then a 'Row' column, containing the name of the row the outlier is on, will be included in the response CSV. If true and the 'data' property is given then it is required that the first column of the input CSV contains the row headers.

Responses

Request samples

Content type
application/json
{
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "data": "x,x^2,x^3,x^4\n3,9,72,81\n2,4,8,16\n",
  • "outlierTolerance": 1,
  • "returnRowHeaders": false
}

Response samples

Content type
application/json
{}

Get the predictions used to calculate the model's quality during training Deprecated

Requires that the model was trained with validation set to 80/20 or 5-fold.

Returns the validation predictions generated for assessing model performance during training. For 5-fold validation, this is the result of training 5 sub-models on 80% and predicting on the remaining 20%, such that the each row in dataset is represented in exactly one validation set. For 80/20 validation, 20% of the dataset is selected at random to form the validation set. This endpoint has been deprecated, please use PUT /models/{id}/validation-predictions instead.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Get the predictions used to calculate the model's quality during training

Requires that the model was trained with validation set to 80/20 or 5-fold.

Returns validation predictions for given columns so that the model training performance can be evaluated. For 5-fold validation, this is the result of training 5 sub-models on 80% and predicting on the remaining 20%, such that the each row in dataset is represented in exactly one validation set. For 80/20 validation, 20% of the dataset is selected at random to form the validation set.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
columns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as columns in the CSV response. If not given then all the columns in the training dataset will be included in the order of the model's trainingColumnHeaders property.

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ]
}

Response samples

Content type
application/json
{}

Find the outlying values in the model's training dataset

Requires that the model was trained with enableTrainingDatasetOutliers set to true.

Compares the training dataset with the corresponding predicted values using the requested validation splits. If the model's validationMethod is '5-fold', each will be trained on 80% of the full dataset to identify the outliers in the remaining 20%. If the model's validationMethod is 'custom', each row in a test set will be checked against a model trained on the matching train set. Please note, if validationMethod is '80/20', only the validation 20% will report outliers, and is thus not recommended.

If a given value lies outside of the error bounds of the corresponding predicted value then it is deemed an outlier. Returns the given value of all outliers along with the corresponding predicted values, the number of standard deviations between the given and predicted values and the row and column indices of the outlier. If the outlier is part of a vector then the "Component Index" indicates which component of the vector is an outlier. If the outlier is not a vector then the "Component Index" will be 1.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
rowIDs
Array of strings non-empty unique

The IDs of the rows to return outliers for. If not given then outliers for all rows in the dataset will be returned.

Responses

Request samples

Content type
application/json
{
  • "rowIDs": [
    ]
}

Response samples

Content type
application/json
{}

Suggest which missing values to measure next

Get suggestions for which missing values to measure next from a given subset of rows and columns in a dataset in order to best improve subsequent predictions for a given set of target columns.

Part of the underlying algorithm uses the imputed values so a quicker response will be obtained if the imputedData is provided as part of the request body.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
One of
datasetID
required
string <uuid>

The ID of a dataset containing at least the columns present in targetColumns or sourceColumns.

sourceRows
Array of strings unique

A list of row headers which all appear in the dataset corresponding to datasetID. Suggested measurements will only be returned from these rows. If not given then the suggestions may come from any row.

sourceColumns
Array of strings

A list of column headers which all appear in the model's training dataset. Suggested measurements will only be returned from these columns. Descriptor columns cannot be in sourceColumns. If not given then suggestions will come from all non-descriptor columns. The sourceColumns may or may not be distinct from the targetColumns.

targetColumns
Array of strings

A list of column headers which all appear in the model's training dataset. Suggested measurements will be targeted to best improve predictions for these columns. Descriptor columns cannot be in targetColumns. If not given then targetColumns will be treated as being all non-descriptor columns. The targetColumns may or may not be distinct from the sourceColumns.

explorationExploitation
number [ 0 .. 1 ]
Default: 1

The desired tradeoff between 'exploration', at 0, or 'exploitation' at 1:

  • 'exploration': suggesting measurements to improve the model across a wide range of different input and output ranges
  • 'exploitation': suggesting measurements that the model in its current state thinks will give the highest model improvement; typically results in more localised suggestions than 'exploration'
numSuggestions
integer [ 1 .. 10000 ]
Default: 1

The maximum number of suggested measurements to return that will best improve predictions for the requested targetColumns.

sFactor
number or null [ 0 .. 1 ]

Where data is mostly missing, sFactor should take low values - when data is mostly complete, it should take higher values. If not given or null then sFactor will be set automatically, which is generally recommended. Adjusting sFactor can make significant differences to the suggestions returned.

uncertaintyWeight
number ( 0 .. 1 ]
Deprecated

Weighting determining the importance of uncertainties for individual data points compared to inter-column relationships when calculating suggested measurements. If 0 then only column relationships are used to produce suggestions, while if 1 then uncertainties are treated as more important. Deprecated, this parameter is no longer supported.

Responses

Request samples

Content type
application/json
Example
{
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "sourceRows": [
    ],
  • "sourceColumns": [
    ],
  • "targetColumns": [
    ],
  • "explorationExploitation": 1,
  • "numSuggestions": 1,
  • "sFactor": 1,
  • "uncertaintyWeight": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Get model sensitivity at a point

Generate a sensitivity analysis around a point. This reports how strongly each column depends on each other column at that point.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
Array of objects (columnValue)

A single point in your parameter space described by an array of objects with key:value pairs representing the column names and their values. Every column in the model's training dataset must have a value.

outputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as rows in the CSV response.
If not given then all continuous target columns in the training dataset will be included in the order of appearance in the model's trainingColumnHeaders property. Categorical and ordinal columns are currently not supported.

inputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as columns in the CSV response. If not given then all the columns in the training dataset will be included in the order of the model's trainingColumnHeaders property.

Responses

Request samples

Content type
application/json
{
  • "dataPoint": [
    ],
  • "outputColumns": [
    ],
  • "inputColumns": [
    ]
}

Response samples

Content type
text/csv
,x,2x
x,0,0.5
2x,2,0

Get model additive sensitivity at a point

Generate an additive sensitivity analysis around a point. This reports the additive contributions of input columns to each output column around a datapoint, similar to coefficients in a local linear regression.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
Array of objects (columnValueNullable)

A single point in your parameter space described by an array of objects with key:value pairs representing the column names and their values.

outputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as rows in the CSV response.
If not given then all continuous target columns in the training dataset will be included in the order of appearance in the model's trainingColumnHeaders property. Categorical and ordinal columns are currently not supported.

inputColumns
Array of strings non-empty

A list of the training dataset's column names to include, in the list's order, as columns in the CSV response. If not given then all the columns in the training dataset will be included in the order of the model's trainingColumnHeaders property.

Array of objects

An optional single point in your parameter space described by an array of objects with key:value pairs representing the column names and their values. It is used to set a baseline value for each column, which the additive sensitivity of the provided data point is calculated with respect to. For instance, the 'current best' entry could be provided as a reference point to compare differences to a new data point. If no specific point is given, the mean/mode of the dataset will be used.

Responses

Request samples

Content type
application/json
{
  • "dataPoint": [
    ],
  • "outputColumns": [
    ],
  • "inputColumns": [
    ],
  • "origin": [
    ]
}

Response samples

Content type
text/csv
,x1,x2,y1,y2
x1,0.0,0.0,0.0,0.0
x2,0.0,0.0,0.0,0.0
y1,0.2,1.2,0.0,0.0
y2,0.275862,1.655172,2.068966,0.0

Get tolerance of predicted outputs from variations in inputs

Explore over an input space and make imputations based on sampled values from provided input ranges. These resultant outputs can then be evaluated to judge how much the output changes in relation to these variable inputs. The tolerance of the output can then be evaluated based on how sensitive it is to changing inputs.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
object (OTSampleDefinition) non-empty

The target columns and their associated ranges to sample values within. At least one column with a valid sample range must be specified.

required
object (OTSetInputs)

The columns that have a set value.

numSamples
integer >= 1
Default: 500

The number of predictions to make during the exploration of the input range space. If using categorical values in the sampleDefinition, numSamples must be at least the length of the largest list of values. This is to ensure all categorical values are samples at least once. If using only categoricals in the sampleDefinition, if all possible combinations of categorical values can be achieved before hitting the value of numSamples, then only this many will be returned. This is to avoid re-sampling combinations that have already been seen as the results will be identical. Neither the sampleDefinition nor the setInputs may contain a calculated column

Responses

Request samples

Content type
application/json
{
  • "sampleDefinition": {
    },
  • "setInputs": {
    },
  • "numSamples": 5
}

Response samples

Content type
application/json
{
  • "fixedInputs": [
    ],
  • "sampledInputs": [
    ],
  • "predictedOutputs": [
    ]
}

Get the univariate tolerances of predicted outputs from variations in inputs

For each specified column, explore over a single input space and make imputations based on sampled values from provided input ranges. These resultant outputs can then be evaluated to judge how much the output changes in relation to these variable inputs. The tolerance of each output can then be evaluated based on how sensitive they are to changing inputs.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
object (OTSampleDefinition) non-empty

The target columns and their associated ranges to sample values within. At least one column with a valid sample range must be specified.

required
object (OTSetInputs)

The columns that have a set value.

numSamples
integer >= 1
Default: 500

The number of predictions to make during the exploration of the input range space. If using categorical values in the sampleDefinition, numSamples must be at least the length of the largest list of values. This is to ensure all categorical values are samples at least once. If using only categoricals in the sampleDefinition, if all possible combinations of categorical values can be achieved before hitting the value of numSamples, then only this many will be returned. This is to avoid re-sampling combinations that have already been seen as the results will be identical. Neither the sampleDefinition nor the setInputs may contain a calculated column

Responses

Request samples

Content type
application/json
{
  • "sampleDefinition": {
    },
  • "setInputs": {
    },
  • "numSamples": 5
}

Response samples

Content type
application/json
{
  • "Size": {
    },
  • "B": {
    }
}

Get all suggest-additional jobs for a model

Get all suggest-additional jobs for a given model

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Suggest additional measurements

Suggest additional measurements in the form of new rows that could be added to the training dataset to improve future models

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
name
string

Optional name to attach to the job.

tags
Array of strings unique

Optional tags to attach to the job. Array should contain unique strings.

notes
string

An optional free field for notes about the job.

required
object (SampleDefinition) non-empty

Dictionary defining the search space that is able to be explored.

required
object (TargetFunction) non-empty

Dictionary of (potentially multiple) targets to optimize against. The cost function for optimization can be considered to be 1 minus the probability of the given sample to achieve the targets. The probability function, for each target, accounts for the prediction and the uncertainty in that prediction. Using multiple targets, the overall cost function is 1 minus the probability that all targets are achieved; this is the product of the individual target probabilities. The key value should be a made up name to give the defined target. When importance is specified, the importance factors are included as linear weights on the probabilities in log-probability space. Only certain columns can be included in the targetFunction:

  • The target column cannot be empty in the training dataset used to create the model.
  • Columns specified as setInputs cannot also be specified as a target column.
  • If the target is also a descriptor column, then it must be specified either in the sampleDefinition or as a dependentColumn.
  • If the target is a categorical column, then it cannot be also specified in the sampleDefinition.
Array of Sum/Mean (object) or Ratio (object) or Weighted Sum/Mean (object) or Weighted Sum/Mean By (Inverse) Column (object) or Product (object) or Constant Sum (object) or Constant Weighted Sum (object) or Zero If Zero (object) or Weighted Ratio (object) (NewColumns)
Deprecated

Deprecated, use dependentColumns instead. Define any dependent columns that exist in the dataset. Categorical columns cannot be dependant on other columns, nor can they have columns depending on them.

Array of Sum/Mean (object) or Ratio (object) or Weighted Sum/Mean (object) or Weighted Sum/Mean By (Inverse) Column (object) or Product (object) or Constant Sum (object) or Constant Weighted Sum (object) or Zero If Zero (object) or Weighted Ratio (object) (DependentColumns)

Define any dependent columns that exist in the dataset. Categorical columns cannot be dependant on other columns, nor can they have columns depending on them. The dependent column cannot also appear in the sampleDefinition nor setInputs, although this is not true for the 'zero if zero' case.

object (SetInputs)

Define set values for columns.

numOptimizationSamples
integer >= 1
Default: 1000

The number of optimization samples that will be considered. Defaults to 1000. The maximum is set per user and defaults to 10000.

optimizationMethod
string
Default: "TPE"
Enum: "TPE" "random" "powell" "nelder-mead" "l-bfgs-b" "bfgs" "conjugate gradient" "cobyla" "slsqp" "tnc"

The following global optimization methods are available:

  • "TPE": Tree-structured Parzen Estimator
  • "random": Random search

The following local optimization methods are available:

  • "powell": Recommended local optimization method
  • "nelder-mead", "l-bfgs-b", "bfgs", "conjugate gradient", "cobyla", "slsqp", "tnc": Other local optimization methods

NOTE: local optimization only supports the following "sample definition" types: "continuous", "continuous or zero" and "categorical"

Defaults to "TPE".

uniqueSamples
boolean
Default: true

If true only return one suggested measurement for each sample. If false then multiple suggestions may appear for the same sample.

explorationExploitation
number [ 0 .. 1 ]
Default: 0.8

The desired tradeoff between 'exploration', at 0, or 'exploitation' at 1:

  • 'exploration': suggesting measurements to improve the model so that future suggestions may better meet the target parameters
  • 'exploitation': suggesting measurements that the model in its current state thinks will best meet the target parameters
sourceColumns
Array of strings or null
Default: []

A list of column headers which all appear in the model's training dataset. Suggested measurements will only be returned from these columns. Descriptor columns cannot be in sourceColumns. By default an empty array, in which case the sourceColumns will be same as targetColumns. If null then all the non-descriptor columns will be treated as the sourceColumns.

targetColumns
Array of strings or null
Default: []

A list of column headers which all appear in the model's training dataset. Suggested measurements will be targeted to best improve predictions for these columns. Descriptor columns cannot be in targetColumns. The targetColumns may or may not be distinct from the sourceColumns. By default an empty array, in which case the targetColumns will be those columns that appear in the targetFunction. If null then all the non-descriptor columns will be treated as the targetColumns.

numSuggestions
integer [ 1 .. 10000 ]
Default: 1

The maximum number of suggested measurements to return that will best improve predictions for the requested targetColumns.

sFactor
number or null [ 0 .. 1 ]

Where data is mostly missing, sFactor should take low values - when data is mostly complete, it should take higher values. If not given or null then sFactor will be set automatically, which is generally recommended. Adjusting sFactor can make significant differences to the suggestions returned.

uncertaintyWeight
number ( 0 .. 1 ]
Deprecated

Weighting determining the importance of uncertainties for individual data points compared to inter-column relationships when calculating suggested measurements. If 0 then only column relationships are used to produce suggestions, while if 1 then uncertainties are treated as more important. Deprecated, this parameter is no longer supported.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "sampleDefinition": {
    },
  • "targetFunction": {
    },
  • "newColumns": [
    ],
  • "dependentColumns": [
    ],
  • "setInputs": {
    },
  • "numOptimizationSamples": 1000,
  • "optimizationMethod": "TPE",
  • "uniqueSamples": true,
  • "explorationExploitation": 0.8,
  • "sourceColumns": [
    ],
  • "targetColumns": [
    ],
  • "numSuggestions": 1,
  • "sFactor": 1,
  • "uncertaintyWeight": 0
}

Response samples

Content type
application/json
{}

Get suggest-additional job data

Get job metadata and, if available, the suggestions

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "enqueueTime": 0,
  • "startTime": 0,
  • "endTime": 0,
  • "sharing": {
    },
  • "parameters": {
    },
  • "status": "pending"
}

Update a suggest additional jobs's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the job. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the job

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Delete suggest-additional job

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
{}

Get all suggest-historic jobs for a model

Get all suggest-historic jobs for a given model

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Suggest historic measurements

Suggest historic measurements from an existing dataset that are likely to meet user-specified target criteria. Predictions and uncertainties for missing values in the dataset are used to compute the probability that each historic measurement has of meeting the target criteria.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
name
string

Optional name to attach to the job.

tags
Array of strings unique

Optional tags to attach to the job. Array should contain unique strings.

notes
string

An optional free field for notes about the job.

datasetID
required
string <uuid>

The ID of a dataset to search within. The dataset must have the same column headers as the model's training dataset.

required
object (HistoricTargetFunction) non-empty

Dictionary of (potentially multiple) targets that returned samples should meet. If more than one target, the cost function from each will be multiplied together. The key value should be a made up name to give the defined target.

numSuggestions
required
integer [ 1 .. 500 ]

The target number of rows to be returned. May return greater than this number where too many rows meet the criterion without any imputed values, and may return fewer if too few results are meet the provided criteria. If the provided criteria would return more than 500 rows, the sample will be truncated.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "datasetID": "65738026-196a-4cf8-9661-9bd286e25a71",
  • "targetFunction": {
    },
  • "numSuggestions": 1
}

Response samples

Content type
application/json
{}

Get suggest-historic job data

Get job metadata and, if available, the results

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "enqueueTime": 0,
  • "startTime": 0,
  • "endTime": 0,
  • "sharing": {
    },
  • "parameters": {
    },
  • "status": "pending"
}

Update a suggest historic jobs's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the job. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the job

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Delete suggest-historic job

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
{}

Get all optimize jobs for given model ID

Get all optimize jobs for given model ID

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

query Parameters
n_samples
integer [ 1 .. 10 ]
Default: 1

Set number of samples to return (i.e. top N samples). Only applies when the optimization status is done and the result is returned. Defaults to 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Optimize for specified targets using set of constraints

Specify sample definition and target function to optimize for.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
required
object (SampleDefinition) non-empty

Dictionary defining the search space that is able to be explored.

required
object (TargetFunction) non-empty

Dictionary of (potentially multiple) targets to optimize against. The cost function for optimization can be considered to be 1 minus the probability of the given sample to achieve the targets. The probability function, for each target, accounts for the prediction and the uncertainty in that prediction. Using multiple targets, the overall cost function is 1 minus the probability that all targets are achieved; this is the product of the individual target probabilities. The key value should be a made up name to give the defined target. When importance is specified, the importance factors are included as linear weights on the probabilities in log-probability space. Only certain columns can be included in the targetFunction:

  • The target column cannot be empty in the training dataset used to create the model.
  • Columns specified as setInputs cannot also be specified as a target column.
  • If the target is also a descriptor column, then it must be specified either in the sampleDefinition or as a dependentColumn.
  • If the target is a categorical column, then it cannot be also specified in the sampleDefinition.
Array of Sum/Mean (object) or Ratio (object) or Weighted Sum/Mean (object) or Weighted Sum/Mean By (Inverse) Column (object) or Product (object) or Constant Sum (object) or Constant Weighted Sum (object) or Zero If Zero (object) or Weighted Ratio (object) (NewColumns)
Deprecated

Deprecated, use dependentColumns instead. Define any dependent columns that exist in the dataset. Categorical columns cannot be dependant on other columns, nor can they have columns depending on them.

Array of Sum/Mean (object) or Ratio (object) or Weighted Sum/Mean (object) or Weighted Sum/Mean By (Inverse) Column (object) or Product (object) or Constant Sum (object) or Constant Weighted Sum (object) or Zero If Zero (object) or Weighted Ratio (object) (DependentColumns)

Define any dependent columns that exist in the dataset. Categorical columns cannot be dependant on other columns, nor can they have columns depending on them. The dependent column cannot also appear in the sampleDefinition nor setInputs, although this is not true for the 'zero if zero' case.

object (SetInputs)

Define set values for columns.

numOptimizationSamples
integer >= 1
Default: 1000

The number of optimization samples that will be considered. Defaults to 1000. The maximum is set per user and defaults to 10000.

optimizationMethod
string
Default: "TPE"
Enum: "TPE" "random" "alchemite" "local alchemite" "powell" "nelder-mead" "l-bfgs-b" "bfgs" "conjugate gradient" "cobyla" "slsqp" "tnc"

The following global optimization methods are available:

  • "TPE": Tree-structured Parzen Estimator
  • "random": Random search
  • "alchemite": Use Alchemite's optimize method

The "alchemite" method only supports the "continuous" sample definition type.

The following local optimization methods are available:

  • "local alchemite": Use Alchemite's local optimize method
  • "powell": Recommended local optimization method
  • "nelder-mead", "l-bfgs-b", "bfgs", "conjugate gradient", "cobyla", "slsqp", "tnc": Other local optimization methods

Local optimization only supports the following "sample definition" types: "continuous", "continuous or zero" and "categorical". The "composition" types can also be used for optimizationMethods "cobyla" and "slsqp"

The "alchemite" and "local alchemite" methods cannot be used with dependentColumns; models trained on datasets containing vectors or calculatedColumns; or targetFunctions other than "between", "below" or "above"

name
string

Optional name to attach to the optimization.

tags
Array of strings unique

Optional tags to attach to the optimization. Array should contain unique strings.

notes
string

An optional free field for notes about the optimisation job.

Responses

Request samples

Content type
application/json
{
  • "sampleDefinition": {
    },
  • "targetFunction": {
    },
  • "newColumns": [
    ],
  • "dependentColumns": [
    ],
  • "setInputs": {
    },
  • "numOptimizationSamples": 1000,
  • "optimizationMethod": "TPE",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Get optimize job data

Request information about an optimize job.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

query Parameters
n_samples
integer [ 1 .. 10 ]
Default: 1

Set number of samples to return (i.e. top N samples). Only applies when the optimization status is done and the result is returned. Defaults to 1

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "parameters": {
    },
  • "enqueueTime": 0,
  • "startTime": 0,
  • "endTime": 0,
  • "sharing": {
    },
  • "status": "pending"
}

Update an optimize jobs's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the job. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the job

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Delete optimize job

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
{}

Share model with a group

Add a group to a model which allows all users belonging to that group to have access to the model

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Stop sharing model with group

Delete group from model's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Get groups with which model is shared

Get model's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a PDF report for the model

Generate a PDF report for the chosen model. This report will contain statistical information on the training dataset, notable features of the model, and multiple plots explaining trends in the data.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the model.

Responses

Response samples

Content type
application/json
{}

Projects

Creating and using a project.

Define a project

Create new project and return the project ID associated with it.

Authorizations:
oauth
Request Body schema: application/json
required

A JSON object containing the name and metadata for the project.

name
required
string
tags
Array of strings unique

Optional tags to attach to the project

notes
string

An optional free field for notes about the dataset

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

List the metadata for every project

Authorizations:
oauth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get project metadata

Get project data

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Responses

Response samples

Content type
application/json
{
  • "id": "00112233-4455-6677-8899-aabbccddeeff",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "createdAt": 0,
  • "modelCount": 0,
  • "suggestInitialCount": 0,
  • "sharing": {
    }
}

Update a project's metadata

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the project. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the project

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{}

Delete project

Deletes the project. Any associated resources will be removed from the project but continue to exist.

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Responses

Response samples

Content type
application/json
{}

Share project with a group

Add a group to a project which allows all users belonging to that group to have access to the project

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Stop sharing project with group

Delete group from project's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Request Body schema: application/json
required
group
required
string

The full path of a group.

Responses

Request samples

Content type
application/json
{
  • "group": "/Organization Name/Group Name"
}

Response samples

Content type
application/json
{}

Get groups with which project is shared

Get project's shared groups

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Move a number of models into or out of a project

Move a large number of models into or out of projects. If a model being moved into a project is already in another project, it will first be removed from its current project

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Request Body schema: application/json
required
add
Array of strings <uuid> non-empty unique [ items <uuid > ]

List of model ids to add to the project

remove
Array of strings <uuid> non-empty unique [ items <uuid > ]

List of model ids to remove from the project

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{}

Move a number of suggest-initial jobs into or out of a project

Move a large number of suggest-initial jobs into or out of projects. If a suggest-initial jobs being moved into a project is already in another project, it will first be removed from its current project

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the project.

Request Body schema: application/json
required
add
Array of strings <uuid> non-empty unique [ items <uuid > ]

List of suggest-initial job ids to add to the project

remove
Array of strings <uuid> non-empty unique [ items <uuid > ]

List of suggest-initial job ids to remove from the project

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{}

Jobs

Aggregate queries for jobs across models.

Sort and filter suggest-additional, suggest-historic & optimize metadata

Returns all suggest-additional, suggest-historic and optimize jobs matching the query passed.

Authorizations:
oauth
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 100 ]
Default: 20

The number of items to return.

Request Body schema: application/json
types
required
Array of strings non-empty unique
Items Enum: "optimize" "suggest-additional" "suggest-historic"

The types of jobs to return

Array of objects = 1 items

Sort the result by the job's attributes.

object non-empty

Filter jobs based on job and model attributes. Note that currently each filter is AND'ed. If a requested job type doesn't have the required attribute, it will be omitted from the results

Responses

Request samples

Content type
application/json
{
  • "types": [
    ],
  • "sort": [
    ],
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "total": 0,
  • "result": [
    ]
}

Creates a favourited job

Create new reference to a favourite job and optionally favourite result within the job

Authorizations:
oauth
Request Body schema: application/json
jobID
required
string <uuid>

The ID of the job being marked as a favourite

resultIndices
Array of integers

The indices of the favourite results in the favourited job

Responses

Request samples

Content type
application/json
{
  • "jobID": "9d2fedc8-0aa5-417a-9010-924207d2319b",
  • "resultIndices": [
    ]
}

Response samples

Content type
application/json
{}

Get all jobs marked as favourited

Returns specified jobs marked as favourited

Authorizations:
oauth
Request Body schema: application/json
object non-empty

Filter favourite jobs based on model attributes.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Gets job from favourites

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the favourite resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "jobID": "9d2fedc8-0aa5-417a-9010-924207d2319b",
  • "resultIndices": [
    ],
  • "modelID": "17448b37-e359-404a-84aa-35f10765ba44"
}

Updates job in favourites

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the favourite resource.

Request Body schema: application/json
resultIndices
Array of integers

The indices of the favourite results in the favourited job. This will replace the previous value for resultIndices on the job

Responses

Request samples

Content type
application/json
{
  • "resultIndices": [
    ]
}

Response samples

Content type
application/json
{}

Removes job from favourites

Authorizations:
oauth
path Parameters
id
required
string <uuid>
Example: 00112233-4455-6677-8899-aabbccddeeff

Unique identifier for the favourite resource.

Responses

Response samples

Content type
application/json
{}

Metrics

Application performance metrics

List the metrics for consumption by Prometheus

Authorizations:
oauth

Responses

Get API and application versions

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "APIDefinitionVersion": "0.12.1",
  • "APIApplicationVersion": "0.1.0",
  • "AlchemiteVersion": "20191113"
}

Suggest initial DoE experiments without a trained model

Suggest initial DoE experiments without a trained model Performing the suggested experiments could serve as the basis for an initial dataset to train a model with.

Authorizations:
oauth
Request Body schema: application/json
required
name
string

Optional name to attach to the job.

tags
Array of strings unique

Optional tags to attach to the job. Array should contain unique strings.

notes
string

An optional free field for notes about the job.

projectId
string <uuid>
required
object (SISampleDefinition) non-empty

Definition of the search space that can be explored.

numSuggestions
integer [ 1 .. 10000 ]
Default: 2

The number of suggested measurements to return.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff",
  • "sampleDefinition": {
    },
  • "numSuggestions": 2
}

Response samples

Content type
application/json
{}

Get all suggest-initial jobs

Get all suggest-initial jobs

Authorizations:
oauth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get suggest-initial job data

Get suggest-initial job data

Authorizations:
oauth
path Parameters
job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "enqueueTime": 0,
  • "startTime": 0,
  • "endTime": 0,
  • "parameters": {
    },
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff",
  • "sharing": {
    },
  • "status": "pending"
}

Update a suggest initial jobs's metadata

Authorizations:
oauth
path Parameters
job_id
required
string <uuid>

Unique ID of the job

Request Body schema: application/json
name
string
tags
Array of strings unique

Optional tags to attach to the job. This replaces any previous tags that may exist

notes
string

An optional free field for notes about the job

projectId
string or null <uuid>

The project this job belongs to. The user must have permission to see the respective project to set this value. Set to null to remove from current project.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "notes": "string",
  • "projectId": "00112233-4455-6677-8899-aabbccddeeff"
}

Response samples

Content type
application/json
{}

Delete suggest-initial job

Authorizations:
oauth
path Parameters
job_id
required
string <uuid>

Unique ID of the job

Responses

Response samples

Content type
application/json
{}

Query the datastore

Returns all rows matching the query passed. Will only return results on datasets that are in the 'uploaded' state.

Authorizations:
oauth
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 5000 ]
Default: 20

The number of items to return.

Request Body schema: application/json
required
One of
type
required
string
Value: "dataset"
id
required
string (Dataset ID)
object non-empty

Filter on dataset columns. Filtering a column on null, e.g. {"my_column": null}, will return rows where the column has no value, i.e. is empty. Note that currently each filter is AND'ed. Currently only null filtering can be applied on vector columns.

Exclude list (object) or Include list (object)

Select which columns to return. If not given than all columns will be returned.

Array of objects

Sort result by the dataset column values. This sorts everything by the first column in list first, and then by the subsequent column whenever the previous column has two or more equal values, i.e. to break ties. If not set, the order is unknown but will be consistent across equal queries. It's currently not possible to sort on vector columns.

object

Responses

Request samples

Content type
application/json
Example

Simple query description

{
  • "type": "dataset",
  • "id": "7d96832c-7f9c-489a-8db1-6957dbdbb1a2",
  • "rowIDs": {
    }
}

Response samples

Content type
application/json
{
  • "type": "dataset",
  • "total": 1,
  • "result": [
    ]
}