Create a new WML training

POST /ml/v4/trainings

Create a new WML training.

Request

Request Body

training_resource_entity_request

experiment

Rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

pipeline

pipeline_rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

model_type

string

The underlying model type produced by the pipeline or by the model_definition.

data_bindings

array

The data bindings.

nodes_parameters

array

The node parameters.

hardware_spec

object

A hardware specification.

hybrid_pipeline_hardware_specs

array

Hybrid pipeline hardware specification.

model_definition

model_definition_rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

model_type

string

The underlying model type produced by the pipeline or by the model_definition.

hardware_spec

object

A hardware specification.

software_spec

object

A software specification.

command

string

If present, it overrides the command specified to the library resource itself.

parameters

object

Optional key-value pairs parameters.

federated_learning

Federated Learning.

model

object

The model type for federated_learning.

fusion_type

Required *

string

The fusion type for federated learning. For an in-depth description of each fusion type, please refer to here.

`iter_avg` - Simple Avg, simplest aggregation that is used as a baseline where all parties' model updates are equally weighted.
`avg` - Weighted Avg, weights the average of updates based on the number of each party sample. Use with training data sets of widely differing sizes.
`pfnm` - Probabilistic Federated Neural Matching (PFNM), communication-efficient method for fully connected neural networks when parties have heterogeneous data sets.
`spahm` - K-Means/SPAHM, used to train KMeans (unsupervised learning) models when parties have heterogeneous data sets.
`xgb_classifier` - XGBoost Classification, used to build classification models that use XGBoost.
`xgb_regressor` - XGBoost Regression, used to build regression models that use XGBoost.
`crypto_iter_avg` - Iterative averaging based fusion implemented with a crypto system.

remote_training

Required *

object

The remote training for federated learning.

rounds

integer

The number of training iterations to complete between the aggregator and the remote systems unless termination accuracy is achieved first.

termination_predicate

string

A boolean expression that describes the conditions, in terms of model metrics, under which training should complete.

epochs

integer

The total number of passes over the local training dataset to train a model.

optimizer

object

The optimizer for federated learning.

loss

string

The loss function to use in the boosting process.

metrics

string

The metrics for federated learning.

max_depth

integer

The maximum depth of each tree.

learning_rate

number

Controls how rapidly to change the model in response to the estimated error each time the model weights are updated.

l2_regularization

number

The coefficient for the L2 regularizer.

max_bins

integer

The maximum number of bins to use for non-missing values across all features.

max_leaf_nodes

integer

The maximum number of leaves for each tree.

min_samples_leaf

integer

The minimum number of samples per leaf.

random_state

integer

Seed used to set the pseudo-random number generator.

verbose

boolean

A general programming term to produce logging output

num_classes

integer

Number of target classes for the classification model.

byzantine_threshold

integer

Specifies the failure tolerance, for example the maximum number of parties that would possibly be failing during training.

sigma

number

Specifies how far the local model neurons are allowed from the global model.

sigma0

number

Specifies the standard deviation of the global network neurons.

gamma

number

Specifies the expected number of features present in each observation.

iters

integer

Specifies the number of iterations of randomly initialized matching-unmatching procedure is to be performed.

save_intermediate_models

boolean

If true, save the model generated at the end of each round of training.

crypto

object

Settings for cryptographic fusion for federated learning.

hardware_spec

object

A hardware specification.

software_spec

object

A software specification.

version

string

The version for federated learning.

log_level

string

The log level (`critical`, `error`, `warning`, `info`, `debug`) for federated learning.

sketch_accuracy_vs_privacy

number

Used with XGBoost training to control the relative accuracy of sketched data sent to the aggregator. Higher values will result in higher quality models but with a reduction in data privacy and increase in resource consumption.

training_data_references

array

Training datasets.

results_reference

Required *

object

The training results.

type

Required *

string

The data source type.

The possible types will depend on the API and platform being used.

location

Required *

object

Contains a set of fields that describe the location of the data with respect to the `connection`.

connection

object

Contains a set of fields specific to each connection. See here for details about specifying connections.

id

string

Item identification inside a collection, if appropriate.

test_data_references

array

The holdout/test datasets.

custom

Custom

User defined properties specified as key-value pairs.

tags

Tags

A list of tags for this resource.

name

string

The name of the training.

description

string

A description of the training.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

Response

201 - The training job has been created.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the list of trainings

GET /ml/v4/trainings

Retrieve the list of trainings for the specified space or project.

Request

Path Parameters

Query Parameters

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. Default value is 100. Max value is 200.

total_count

boolean

Compute the total count. May have performance impact.

tag.value

string

Return only the resources with the given tag value.

type

string

Filter based on 'pipeline' or 'experiment' trainings. Example: `type=pipeline`. If not provided, returns all the trainings.

state

string

Filter based on on the training job state: queued, running, completed, failed etc.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

parent_id

string

Return the training jobs that are sub-jobs of this parent_id job. The parent_id can be the experiment job ID.

Response

200 - OK.

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the training

GET /ml/v4/trainings/{training_id}

Retrieve the training with the specified identifier. This call supports Web-Socket upgrade. However in order to preserve bandwidth, web-socket messages are not context complete. Meaning that a single web-socket message only reflects a message or metric happening in the context of a training job or sub-job (in case of experiment trainings or HPO/AutoML trainings). Hence the metadata property of a web-socket message contains a parent with the href information of the parent job that triggered this particular job. Also the metrics will be provided as they arrive from the backend runtime, and not as a cumulative list. In order to get the full view of the running training job the caller should do a regular GET call.

Request

Response

101 - In case of web socket upgrade, the service messages emitted have the following shape.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_status

Status of the model.

200 - OK.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Cancel the training

DELETE /ml/v4/trainings/{training_id}

Cancel the specified training and remove it.

Request

Path Parameters

Query Parameters

hard_delete

boolean

Set to true in order to also delete the job metadata information.

Response

204 - Training cancelled.

400 -

401 -

403 -

404 -

Create a new WML deployment

POST /ml/v4/deployments

Create a new deployment, the parameters specifying the deployment type are `online` and `batch`. These parameters are mutually exclusive, specify only one of these when creating a deployment. Use `hybrid_pipeline_hardware_specs` only when creating a `batch` deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other `batch` deployment cases use `hardware_spec` to specify compute configuration. The `hybrid_pipeline_hardware_specs` and `hardware_spec` are mutually exclusive, specify only one of these when creating a deployment. For `batch` deployments, `hardware_spec.num_nodes` parameter is not currently supported. For `online` deployments, `hardware_spec` cannot be specified at the time of creation, `hardware_spec.num_nodes` parameter is not supported as part of `POST /ml/v4/deployments` API request, but it can be updated using `PATCH /ml/v4/deployments/<deployment id>`. For `online` deployments, `serving_name` can be provided in `online.parameters`. The serving name can have the characters `[a-z,0-9,_]` and must not be more than 36 characters. The `serving_name` can be used in the prediction URL in place of the `deployment_id`. See the documentation supported frameworks for details about which frameworks can be used in a deployment.

Request

Request Body

deployment_entity_request

The deployment entity.

custom

Custom

User defined properties specified as key-value pairs.

asset

Rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

hardware_spec

HardwareSpec

A hardware specification.

id

string

The id of the hardware specification.

rev

string

The revision of the hardware specification.

name

string

The name of the hardware specification.

num_nodes

integer

The number of nodes applied to a computation.

hybrid_pipeline_hardware_specs

Hybrid pipeline hardware specification.

online

OnlineRequest

Indicates that this is an online deployment. An empty object has to be specified. If the online scoring schema has a `type` of `DataFrame` then the scoring payload will be converted to a `Pandas` data frame.

parameters

object

A set of key-value pairs where `key` is the parameter name.

batch

BatchRequest

Indicates that this is a batch deployment. An empty object has to be specified.

parameters

object

A set of key-value pairs where `key` is the parameter name.

tags

array

Tags that can be used when searching for resources.

space_id

Required *

string

The space that contains the resource.

name

string

The name of the deployment.

description

string

A description of the deployment.

Response

202 - Deployment created.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

deployment_entity

See the description in `POST /ml/v4/deployments`.

400 -

401 -

403 -

404 -

Retrieve the deployments

GET /ml/v4/deployments

Retrieve the list of deployments for the specified space.

Request

Path Parameters

Query Parameters

space_id

string

Retrieves the deployments that belong to this space.

serving_name

string

Retrieves the deployment, if any, that contains this `serving_name`.

tag.value

string

Retrieves only the resources with the given tag value.

asset_id

string

Retrieves only the resources with the given asset_id, asset_id would be either model_id or function_id.

name

string

Retrieves only the resources with the given name.

type

string

Retrieves the resources filtered with the given type. Allowed values are `model`, `function`, `py_script` and `do`.

state

string

Retrieves the resources filtered by state. Allowed values are `initializing`, `updating`, `ready` and `failed`.

stats

boolean

Returns stats about deployments within a space or across spaces if it is set to true. This query parameter cannot be combined with any other except for 'space_id'.

conflict

boolean

Returns whether serving_name is available for use or not. This query parameter cannot be combined with any other except for 'serving_name'.

Response

200 - OK.

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of deployment resources. This will be empty if 'stats' query parameter is passed with 'true'.

system

object

System details including warnings and stats. This will get populated only if 'stats' query parameter is passed with 'true'.

204 - serving_name is available for use. Returned when serving_name and conflict query parameters are used.

400 -

401 -

403 -

404 -

409 - Returned when serving_name and conflict query parameters are used. The response body will contain the reason.

trace

string

An identifier that can be used to trace the request.

status_code

integer

The corresponding error code in integer.

errors

array

The list of errors.

Retrieve the deployment details

GET /ml/v4/deployments/{deployment_id}

Retrieve the deployment details with the specified identifier.

Request

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

Response

200 - Deployment details.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

deployment_entity

See the description in `POST /ml/v4/deployments`.

400 -

401 -

403 -

404 -

Delete the deployment

DELETE /ml/v4/deployments/{deployment_id}

Delete the deployment with the specified identifier.

Request

Path Parameters

Query Parameters

space_id

Required *

string

Retrieves the deployments of assets that belong to this space.

Response

204 - Deployment deleted.

400 -

401 -

404 -

Update the deployment metadata

PATCH /ml/v4/deployments/{deployment_id}

Update the deployment metadata. The following parameters of deployment metadata are supported for the patch operation.

`/tags` - `/name` - `/description` - `/custom` - `/hardware_spec` - `/hybrid_pipeline_hardware_specs` - `/asset` - `/online/parameters` - `/observability/enable_tracing` In case of online deployments, using PATCH operation of `/ml/v4/deployments`, users can update the number of copies of an online deployment. Users can specify the desired value of number of copies in `hardware_spec.num_nodes` parameter. As `hardware_spec.name` or `hardware_spec.id` is mandatory for `hardware_spec` schema, a valid value such as `XS`, `S` must be specified for `hardware_spec.name` parameter as part of PATCH request. Alternatively, users can also specify a valid ID of a hardware specification in `hardware_spec.id` parameter. However, changes related to `hardware_spec.name` or `hardware_spec.id` specified in PATCH operation will not be applied for online deployments. In case of batch deployments, using PATCH operation of `/ml/v4/deployments`, users can update the hardware specification so that subsequent batch deployment jobs can make use of the updated compute configurations. To update the compute configuration, users must specify a valid value for either `hardware_spec.name` or `hardware_spec.id` of the hardware specification that suits their requirement. In the batch deployment context, `hardware_spec.num_nodes` parameter is not currently supported. When 'asset' is patched with id/rev:
Deployment with the patched id/rev is started. - With an asynchronous deployment (`version` greater than 2021-05-01), 202 response code will be returned and one can poll the deployment for the status.
If any failures, deployment will be reverted back to the previous id/rev and the failure message will be captured in 'failures' field in the response.

In the case of an online deployment, the PATCH operation with path specified as `/online/parameters` can be used to update the `serving_name`.

Request

Request Body

JsonPatch

The json patch.

Path Parameters

Query Parameters

space_id

Required *

string

Retrieves the deployments of assets that belong to this space.

Response

202 - Deployment accepted

metadata

ResourceMeta

Common metadata for a simple resource.

entity

deployment_entity

See the description in `POST /ml/v4/deployments`.

400 -

401 -

403 -

404 -

Execute a synchronous deployment prediction

POST /ml/v4/deployments/{deployment_id}/predictions

Execute a synchronous prediction for the deployment with the specified identifier. If a `serving_name` is used then it must match the `serving_name` that is returned in the `inference` field.

Request

Request Body

sync_scoring_data

The scoring data.

input_data

Required *

array

The input data.

scoring_parameters

ScoringParameters

Parameters that can be used to control the prediction request.

forecast_window

integer

The forecast window to use for the prediction. If no value is set then the value used during training will be used.

Response

200 - Scoring response.

predictions

array

The predictions.

400 -

401 -

403 -

404 -

Retrieve the deployment jobs

GET /ml/v4/deployment_jobs

Retrieve the status of the current jobs. The system will apply a max limit of jobs retained by the system as we cannot accumulate an infinite number of jobs. Only most recent 300 jobs (system configurable) will be preserved. Older jobs will be purged by the system.

Request

Path Parameters

Query Parameters

space_id

Required *

string

Retrieves the deployment jobs that belong to this space.

tag.value

string

Retrieves only the jobs with these tags (comma separated).

state

string

Filter based on on the deployment job state: queued, running, completed, failed etc.

deployment_id

string

Filter based on the deployment_id.

include

string

Retrieves only fields from `decision_optimization` and `scoring` section mentioned as comma separated values as output response fields. Retrieves all the fields if not mentioned.

Response

200 - Jobs response.

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of jobs.

400 -

401 -

403 -

404 -

Start an asynchronous deployment job

POST /ml/v4/deployment_jobs

Start a deployment job asynchronously. This can perform batch scoring, streaming, or other types of batch operations, such as solving a Decision Optimization problem. Depending on the `version` date passed, the `platform_jobs` section in the response may or may not be populated. Use the GET call to retrieve the deployment job, this GET call will eventually populate the `platform_jobs` section. Refer to the `version date` description for more details.

Request

Request Body

job_entity_request

The request body contains information about the batch deployment job that is described in more detail below.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive. Specify only one of these when submitting a batch deployment job, one of these fields must be defined.

Use `hybrid_pipeline_hardware_specs` only in a batch deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other cases use `hardware_spec` to specify compute configuration.

In case of output data references where the data asset is a remote database, users can specify if the batch deployment output must be appended to the table or if the table is to be truncated and output data updated. The `output_data_references.location.write_mode` parameter can be used to for this purpose. The values `truncate` or `append` can be specified for `output_data_references.location.write_mode` parameter.

Specifying `truncate` as value will truncate the table and the batch output data will be inserted.
Specifying `append` as value will insert the batch output data to the remote database table.
The `write_mode` parameter is applicable only for `output_data_references` parameter.
The `write_mode` parameter will be applicable only for remote database related data assets. This parameter will not be applicable for local data assets or a COS based data asset.

space_id

Required *

string

The space that contains the resource.

name

Required *

string

The name of the resource.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

deployment

Required *

SimpleRel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

custom

object

User defined properties.

hardware_spec

HardwareSpec

A hardware specification.

id

string

The id of the hardware specification.

rev

string

The revision of the hardware specification.

name

string

The name of the hardware specification.

num_nodes

integer

The number of nodes applied to a computation.

hybrid_pipeline_hardware_specs

Hybrid pipeline hardware specification.

scoring

job_scoring_request

Details about the input/output data and other properties to be used for a batch deployment job of a model, Python Function or a Python Scripts.

Use `input_data` property to specify the input data for batch processing as part of the job's payload. The `input_data` property is mutually exclusive with `input_data_references` property, only use one of these. When `input_data` is specified, the processed output of batch deployment job will be available in `scoring.predictions` parameter in the deployment job response. `input_data` property is not supported for batch deployment of Python Scripts.

Use `input_data_references` property to specify the details pertaining to the remote source where the input data for batch deployment job is available. The `input_data_references` must be used with `output_data_references`. The `input_data_references` property is mutually exclusive with `input_data` property, only use one of these. The `input_data_references` property is not supported for batch deployment job of Spark models and Python Functions.

Use `output_data_references` property to specify the details pertaining to the remote source where the input data for batch deployment job is available. `output_data_references` must be used with `input_data_references`. The `output_data_references` property is not supported for batch deployment job of Spark models and Python Functions.

input_data

array

A list of payloads.

input_data_references

array

A list of input data references.

output_data_reference

object

A reference to data with an optional data schema. If necessary, it is possible to provide a data connection that contains just the data schema.

evaluations

array

A list of evaluation specifications.

environment_variables

object

This property is used to specify environment variables and their values required to be consumed by the batch deployment job. The environment variables and values must be specified as key-value pairs.

This property is currently supported only for Python Scripts in batch deployment jobs.

decision_optimization

job_decision_optimization_request

Details about the input/output data and other properties to be used for a batch deployment job of a Decision Optimization problem. You can find more information in Deploying Decision Optimization documentation. Use the `solve_parameters` as named value pairs to control the Decision Optimization solve behavior. Use the `input_data` and `output_data` properties to specify respectively input and output data for batch processing as part of the job's payload. Use the `input_data_references` and `output_data_references` properties to specify respectively input and output data for batch processing as remote data sources.

solve_parameters

object

To control solve behavior, you can specify solve parameters in your request as key-value pairs.

input_data

array

A list of payloads.

input_data_references

array

A list of input data references.

output_data

array

A list of output payloads.

output_data_references

array

A list of output data references.

Path Parameters

Query Parameters

retention

string

Defines number of days to retain the job meta. Job meta will be auto deleted after that. Value '-1' sets the meta to be never auto deleted. accepted values are positive integer and '-1'. The default value if the parameter is not passed is '30' days.

Response

202 - Accepted

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_status_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive.

400 -

401 -

403 -

404 -

Cancel the deployment job

DELETE /ml/v4/deployment_jobs/{job_id}

Cancel the specified deployment job.

Request

Path Parameters

Query Parameters

space_id

Required *

string

Cancel the deployment job that belong to this space.

hard_delete

boolean

Set to true in order to also delete the job metadata information.

Response

204 - Success.

400 -

401 -

403 -

404 -

Retrieve the deployment job

GET /ml/v4/deployment_jobs/{job_id}

Retrieve the deployment job. The predicted data bound to this job_id is going to be kept around for a limited time based on the service configuration.

Request

Path Parameters

Query Parameters

space_id

Required *

string

Retrieve the deployment job that belong to this space.

include

string

Retrieves only fields from `decision_optimization` and `scoring` section mentioned as comma separated values as output response fields. Retrieves all the fields if not mentioned.

Response

200 - Jobs response.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_status_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive.

400 -

401 -

403 -

404 -

Retrieve the service instances

GET /ml/v4/instances

Retrieve the service instances. Either `space_id` or `project_id` query parameter is mandatory but both can be provided.

Request

Path Parameters

Query Parameters

space_id

array

Return resources pertaining to any space_id listed. Either `space_id` or `project_id` query parameter is mandatory but both can be provided.

project_id

array

Return resources pertaining to any project_id listed. Either `space_id` or `project_id` query parameter is mandatory but both can be provided.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

consumption_details

boolean

Only if `consumption_details` is set to `true` each instance `entity.consumption.details` part is available in response.

Response

200 - OK.

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

400 -

401 -

403 -

404 -

Retrieve the service instance

GET /ml/v4/instances/{instance_id}

Retrieve the service instance details.

Request

Path Parameters

Query Parameters

space_id

string

Defines authorization context that allows a space member to perform this operation.

project_id

string

Defines authorization context that allows a project member to perform this operation.

consumption_details

boolean

Only if `consumption_details` is set to `true` the instance `entity.consumption.details` part is available in response.

Response

200 - OK.

metadata

ResourceMetaBase

Common metadata for a resource.

entity

instance_resource_entity

400 -

401 -

403 -

404 -

Create a new experiment

POST /ml/v4/experiments

Create a new experiment with the given payload. An experiment represents an asset that captures a set of `pipeline` or `model definition` assets that will be trained at the same time on the same data set.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.create

Request

Request Body

experiment_entity_request

Payload for creating the experiment. Either `space_id` or `project_id` has to be provided and is mandatory.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

label_column

string

The label column.

evaluation_definition

The optional evaluation definition.

method

string

The evaluation method.

metrics

Required *

array

The evaluation metrics.

training_references

array

The optional training references used by the experiment.

custom

Custom

User defined properties specified as key-value pairs.

Response

201 - Experiment created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

experiment_entity

The details of the experiment to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the experiments

GET /ml/v4/experiments

Retrieve the experiments for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

Returns only resources that match this search string. The path to the field must be the complete path to the field, and this field must be one of the indexed fields for this resource type. Note that the search string must be URL encoded.

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

These are the fields that can be searched in the `entity` and that depend on the asset type: - `model` - `/entity/type` - `/entity/software_spec.id` - `function` - `/entity/software_spec.id` - `ai_service` - `/entity/software_spec.id`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of experiments.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the experiment

GET /ml/v4/experiments/{experiment_id}

Retrieve the experiment with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

experiment_entity

The details of the experiment to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the experiment

PATCH /ml/v4/experiments/{experiment_id}

Update the experiment with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Experiment has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

experiment_entity

The details of the experiment to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the experiment

DELETE /ml/v4/experiments/{experiment_id}

Delete the experiment with the specified identifier. This will delete all revisions of this experiment as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Experiment deleted

400 -

401 -

403 -

404 -

Create a new experiment revision

POST /ml/v4/experiments/{experiment_id}/revisions

Create a new experiment revision. The current metadata and content for experiment_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Experiment revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

experiment_entity

The details of the experiment to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the experiment revisions

GET /ml/v4/experiments/{experiment_id}/revisions

Retrieve the experiment revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.experiment.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Experiment revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of experiments.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Create a new function

POST /ml/v4/functions

Create a new function with the given payload. A function is some code that can be deployed as an online, or batch deployment.

Auditing

Calling this method generates the following auditing event.

pm-20.function.create

Request

Request Body

function_entity_request

Payload for creating the function. Either `space_id` or `project_id` has to be provided and is mandatory.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

software_spec

Required *

SoftwareSpecRel

A software specification.

id

string

The id of the software specification.

rev

string

The revision of the software specification.

name

string

The name of the software specification.

type

string

Type of the function to be created. Only `python` type is supported as of now. If not specified, `python` is the default. Functions expect a gzip file that contains a python file that make up the function. Python functions specify what needs to be run when the function is deployed and what needs to be run when the scoring function is called. In other words, you are able to customize what preparation WML does in the environment when you deploy the function, as well as what steps WML takes to generate the output when you call the API later on. The function consists of the outer function (any place that is not within the score function) and the inner score function. The code that sits in the outer function runs when the function is deployed, and the environment is then frozen and ready to be used whenever the online scoring or batch inline job processing API is called. The code that sits in the inner score function runs when the online scoring or batch inline job processing API is called, in the environment customized by the outer function. See Deploying Python function for more details.

This is illustrated in the example below:

><python code used to set up the environment>
>
>def score(payload):
>    df_payload = pd.DataFrame(payload["values"])
>    df_payload.columns = payload["fields"]
>    ...
>    output = {"result" : res}
>    return output
>
>return score

sample_scoring_input

sync_scoring_data

Scoring data.

input_data

Required *

array

The input data.

scoring_parameters

object

Parameters that can be used to control the prediction request.

schemas

object

The schemas of the expected data.

input

array

The schema of the expected input data.

output

array

The schema of the expected output data.

custom

Custom

User defined properties specified as key-value pairs.

model_references

array

This is a list of references of the models that are used by this function, if any. These references are provided by the owner of the function and are used for usage tracking only.

Response

201 - Function created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

function_entity

The details of the function to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the functions

GET /ml/v4/functions

Retrieve the functions for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.function.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of functions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the function

GET /ml/v4/functions/{function_id}

Retrieve the function with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.function.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

function_entity

The details of the function to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the function

PATCH /ml/v4/functions/{function_id}

Update the function with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`

Auditing

Calling this method generates the following auditing event.

pm-20.function.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Function has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

function_entity

The details of the function to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the function

DELETE /ml/v4/functions/{function_id}

Delete the function with the specified identifier. This will delete all revisions of this function as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.function.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Function deleted

400 -

401 -

403 -

404 -

Create a new function revision

POST /ml/v4/functions/{function_id}/revisions

Create a new function revision. The current metadata and content for function_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.function.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Function revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

function_entity

The details of the function to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the function revisions

GET /ml/v4/functions/{function_id}/revisions

Retrieve the function revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.function.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Function revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of functions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Upload the function code

PUT /ml/v4/functions/{function_id}/code

Upload the function code. Functions expect a zip file that contains a python file that make up the function. Python functions specify what needs to be run when the function is deployed and what needs to be run when the scoring function is called. In other words, you are able to customize what preparation WML does in the environment when you deploy the function, as well as what steps WML takes to generate the output when you call the API later on. The function consists of the outer function (any place that is not within the score function) and the inner score function. The code that sits in the outer function runs when the function is deployed, and the environment is then frozen and ready to be used whenever the online scoring or batch inline job processing API is called. The code that sits in the inner score function runs when the online scoring or batch inline job processing API is called, in the environment customized by the outer function. See Deploying Python function for more details. This is illustrated in the example below: <pre> ...python code used to set up the environment... def score(payload): df_payload = pd.DataFrame(payload[values]) df_payload.columns = payload[fields] ... output = {result : res} return output return score </pre>

Auditing

Calling this method generates the following auditing event.

pm-20.function.add

Request

Request Body

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

201 - Function code uploaded

attachment_id

string

The content id for the attachment.

content_format

string

The type of the content.

name

string

The name of the attachment.

pipeline_node_id

string

The `pipeline_node_id` that corresponds to this content.

deployment_id

string

The `deployment_id` that corresponds to this content.

persisted

boolean

This will be set to `true` if the content has been persisted. If this content was part of the import process and the upload of the content failed then the message can be found in the `warnings` field of the `system_details` that are returned with the model details.

400 -

401 -

403 -

404 -

Download the function code

GET /ml/v4/functions/{function_id}/code

Download the function code. It is possible to get the `code` for a given revision of the `function`. Functions expect a zip file that contains a python file that make up the function. Python functions specify what needs to be run when the function is deployed and what needs to be run when the scoring function is called. In other words, you are able to customize what preparation WML does in the environment when you deploy the function, as well as what steps WML takes to generate the output when you call the API later on. The function consists of the outer function (any place that is not within the score function) and the inner score function. The code that sits in the outer function runs when the function is deployed, and the environment is then frozen and ready to be used whenever the online scoring or batch inline job processing API is called. The code that sits in the inner score function runs when the online scoring or batch inline job processing API is called, in the environment customized by the outer function. See Deploying Python function for more details. This is illustrated in the example below: <pre> ...python code used to set up the environment... def score(payload): df_payload = pd.DataFrame(payload[values]) df_payload.columns = payload[fields] ... output = {result : res} return output return score </pre>

Auditing

Calling this method generates the following auditing event.

pm-20.function.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 -

400 -

401 -

403 -

404 -

Create a new pipeline

POST /ml/v4/pipelines

Create a new pipeline with the given payload. A pipeline represents a hybrid-pipeline, as a JSON document, that is used to train one or more models.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.create

Request

Request Body

pipeline_entity_request

Payload for creating the pipeline. Either `space_id` or `project_id` has to be provided and is mandatory.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

document

Required *

object

The pipeline document, see pipeline-flow-v2-schema for the schema definition.

custom

Custom

User defined properties specified as key-value pairs.

Response

201 - Pipeline created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

pipeline_entity

The details of the pipeline to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the pipelines

GET /ml/v4/pipelines

Retrieve the pipelines for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of pipelines.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the pipeline

GET /ml/v4/pipelines/{pipeline_id}

Retrieve the pipeline with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

pipeline_entity

The details of the pipeline to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the pipeline

PATCH /ml/v4/pipelines/{pipeline_id}

Update the pipeline with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Pipeline has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

pipeline_entity

The details of the pipeline to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the pipeline

DELETE /ml/v4/pipelines/{pipeline_id}

Delete the pipeline with the specified identifier. This will delete all revisions of this pipeline as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Pipeline deleted

400 -

401 -

403 -

404 -

Create a new pipeline revision

POST /ml/v4/pipelines/{pipeline_id}/revisions

Create a new pipeline revision. The current metadata and content for pipeline_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Pipeline revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

pipeline_entity

The details of the pipeline to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the pipeline revisions

GET /ml/v4/pipelines/{pipeline_id}/revisions

Retrieve the pipeline revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.pipeline.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Pipeline revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of pipelines.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Create a new model

POST /ml/v4/models

Create a new model with the given payload. A model represents a machine learning model asset. If a `202` status is returned then the model will be ready when the `content_import_state` in the model status (/ml/v4/models/{model_id}) is `completed`. If `content_import_state` is not used then a `201` status is returned.

Auditing

Calling this method generates the following auditing event.

pm-20.model.create

Request

Request Body

model_entity_request

Payload for creating the model. Either `space_id` or `project_id` has to be provided and is mandatory. A software specification is required for all model types except curated models.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

type

Required *

string

The model type. The supported model types can be found in the documentation here.

software_spec

SoftwareSpecRel

A software specification.

id

string

The id of the software specification.

rev

string

The revision of the software specification.

name

string

The name of the software specification.

pipeline

Rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

model_definition

model_definition_id

The model definition.

id

string

The id of the model definition.

hyper_parameters

object

Hyper parameters used for training this model.

domain

string

User provided domain name for this model. For example: sentiment, entity, visual-recognition, finance, retail, real estate etc.

training_data_references

array

The training data that was used to create this model.

test_data_references

array

The holdout/test datasets.

schemas

object

If the prediction schemas are provided here then they take precedent over any schemas provided in the data references. Note that data references contain the schema for the associated data and this object contains the schema(s) for the associated prediction, if any. In the case that the prediction input data matches exactly the schema of the training data references then the prediction schema can be omitted. However it is highly recommended to always specify the prediction schemas using this field.

input

array

The schema of the expected prediction input data, see datarecord-metadata-v2-schema for the schema definition.

output

array

The schema of the expected prediction output data, see datarecord-metadata-v2-schema for the schema definition.

label_column

string

The name of the label column.

transformed_label_column

string

The name of the label column seen by the estimator, which may have been transformed by the previous transformers in the pipeline. This is not necessarily the same column as the `label_column` in the initial data set.

size

object

This will be used by scoring to record the size of the model.

in_memory

number

The memory size of the model.

content

number

The size of the model on disk.

metrics

Metrics

Metrics that can be returned by an operation.

custom

Custom

User defined properties specified as key-value pairs.

user_defined_objects

object

User defined objects referenced by the model. For any user defined class or function used in the model, its name, as referenced in the model, must be specified as the `key` and its fully qualified class or function name must be specified as the `value`. This is applicable for `Tensorflow 2.X` models serialized in `H5` format using the `tf.keras` API.

hybrid_pipeline_software_specs

array

The list of the software specifications that are used by the pipeline that generated this model, if the model was generated by a pipeline.

model_version

object

Optional metadata that can be used to provide information about this model that can be tracked with IBM AI Factsheets. See Using AI Factsheets for more details.

number

string

This is the user-provided version which should follow semantic versioning.

tag

string

This is the user-provided tag for the model.

description

string

This is the user provided description that provides context for the change in the model version.

training_id

string

Deprecated: this is replaced by `training.id`. This field can be used to store the `id` of the training job that was used to produce this model.

data_preprocessing

array

An optional array which contains the data preprocessing transformations that were executed by the training job that created this model.

training

training_details

Information about the training job that created this model.

id

string

The `id` of the training job that produced this model.

base_model

object

The model id of the base model for this job.

task_id

string

The task that is targeted for this model.

verbalizer

string

The optional verbalizer that was used during the training, if appropriate.

content_location

Details about the attachments that should be uploaded with this model.

Required *

array

The content information to be uploaded.

type

Required *

string

The data source type like `connection_asset` or `data_asset`.

connection

object

Connection properties.

location

object

Location properties.

Response

201 - Model created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_resource_entity

The details of the model to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

202 - Model accepted, this is returned in the case that `content_location` was provided

in the request entity and so the model was created but the attachments are still being uploaded. In this case the model will not be ready until the `content_import_state` in the model status (/ml/v4/models/{model_id}) is `completed`.

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_resource_entity

The details of the model to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the models

GET /ml/v4/models

Retrieve the models for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.model.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of models.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model

GET /ml/v4/models/{model_id}

Retrieve the model with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.model.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_resource_entity

The details of the model to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the model

PATCH /ml/v4/models/{model_id}

Update the model with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`
`/software_spec` (operation `replace` only)
`/model_version` (operation `add` and `replace` only)

Auditing

Calling this method generates the following auditing event.

pm-20.model.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Model has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_resource_entity

The details of the model to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the model

DELETE /ml/v4/models/{model_id}

Delete the model with the specified identifier. This will delete all revisions of this model as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.model.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Model deleted

400 -

401 -

403 -

404 -

Create a new model revision

POST /ml/v4/models/{model_id}/revisions

Create a new model revision. The current metadata and content for model_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.model.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Model revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_resource_entity

The details of the model to be created.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model revisions

GET /ml/v4/models/{model_id}/revisions

Retrieve the model revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.model.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Model revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of models.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model content metadata list

GET /ml/v4/models/{model_id}/content

Retrieve the content metadata list for the specified model attachments.

Auditing

Calling this method generates the following auditing event.

pm-20.model.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

name

string

List only attachments with the given name.

content_format

string

This is the format of the content. Any value can be used for the format and is there to be able to easily find content by format.

Response

200 - OK

total_count

integer

The number of attachments associated with the resource.

attachments

array

400 -

401 -

403 -

404 -

Upload the model content

PUT /ml/v4/models/{model_id}/content

Upload the content for the specified model.

Auditing

Calling this method generates the following auditing event.

pm-20.model.add

Request

Request Body

content_json

models file

Path Parameters

Query Parameters

content_format

Required *

string

This is the format of the content. Any value can be used for the format and is there to be able to easily find content by format.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

pipeline_node_id

string

Returns only resources that match this `pipeline_node_id`, this is only relevant if `content_format` is `pipeline-node`.

deployment_id

string

Returns only resources that match this `deployment_id`, this is only relevant if `content_format` is `coreml`.

name

string

Provide the name of the attachment.

Response

201 - Model content uploaded

attachment_id

string

The content id for the attachment.

content_format

string

The type of the content.

name

string

The name of the attachment.

pipeline_node_id

string

The `pipeline_node_id` that corresponds to this content.

deployment_id

string

The `deployment_id` that corresponds to this content.

persisted

boolean

400 -

401 -

403 -

404 -

Download the model content

GET /ml/v4/models/{model_id}/content/{attachment_id}

Download the model content.

Auditing

Calling this method generates the following auditing event.

pm-20.model.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - Downloaded

400 -

401 -

403 -

404 -

Delete the model content

DELETE /ml/v4/models/{model_id}/content/{attachment_id}

Delete the content for the specified model.

Auditing

Calling this method generates the following auditing event.

pm-20.model.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Model content deleted

400 -

401 -

403 -

404 -

Download the model content that matches a certain criteria

GET /ml/v4/models/{model_id}/download

Download the model content identified by the provided criteria. If more than one attachment is found for the given filter then a `400` error is returned. If there are no attachments that match the filter then a `404` error is returned. If there are no filters then, if there is a single attachment, the attachment content will be returned otherwise a `400` or `404` error will be returned as described above. This method is just a shortcut for getting the attachment metadata and then downloading by attachment id.

Auditing

Calling this method generates the following auditing event.

pm-20.model.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

pipeline_node_id

string

Returns only resources that match this `pipeline_node_id`, this is only relevant if `content_format` is `pipeline-node`.

deployment_id

string

Returns only resources that match this `deployment_id`, this is only relevant if `content_format` is `coreml`.

name

string

Match an attachment with this name.

content_format

string

This is the format of the content. Any value can be used for the format and is there to be able to easily find content by format.

Response

200 - Downloaded

400 -

401 -

403 -

404 -

Create a new model definition

POST /ml/v4/model_definitions

Create a new model definition with the given payload. A model definition represents the code that is used to train one or more models.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.create

Request

Request Body

model_definition_entity_request

Payload for creating the model definition. Either `space_id` or `project_id` has to be provided and is mandatory.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

version

Required *

string

The package version.

platform

Required *

object

name

Required *

string

The name of the platform.

versions

Required *

array

The supported versions.

command

string

The command used to run the model.

software_spec

SoftwareSpecRel

A software specification.

id

string

The id of the software specification.

rev

string

The revision of the software specification.

name

string

The name of the software specification.

custom

Custom

User defined properties specified as key-value pairs.

Response

201 - Model definition created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_definition_entity

The definition of a model. The `software_spec` is used only for training. Either space_id or project_id has to be provided and is mandatory.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model definitions

GET /ml/v4/model_definitions

Retrieve the model definitions for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of model definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model definition

GET /ml/v4/model_definitions/{model_definition_id}

Retrieve the model definition with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_definition_entity

The definition of a model. The `software_spec` is used only for training. Either space_id or project_id has to be provided and is mandatory.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the model definition

PATCH /ml/v4/model_definitions/{model_definition_id}

Update the model definition with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Model definition has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_definition_entity

The definition of a model. The `software_spec` is used only for training. Either space_id or project_id has to be provided and is mandatory.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the model definition

DELETE /ml/v4/model_definitions/{model_definition_id}

Delete the model definition with the specified identifier. This will delete all revisions of this model definition as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Model definition deleted

400 -

401 -

403 -

404 -

Create a new model definition revision

POST /ml/v4/model_definitions/{model_definition_id}/revisions

Create a new model definition revision. The current metadata and content for model_definition_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Model definition revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

model_definition_entity

The definition of a model. The `software_spec` is used only for training. Either space_id or project_id has to be provided and is mandatory.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the model definition revisions

GET /ml/v4/model_definitions/{model_definition_id}/revisions

Retrieve the model definition revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Model definition revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of model definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Upload the model definition model

PUT /ml/v4/model_definitions/{model_definition_id}/model

Upload the model definition model. Model definitions for Deep Learning accept a zip file that contains one or more python files organized in any directory structure.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.add

Request

Request Body

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

201 - Model definition model uploaded

attachment_id

string

The content id for the attachment.

content_format

string

The type of the content.

name

string

The name of the attachment.

pipeline_node_id

string

The `pipeline_node_id` that corresponds to this content.

deployment_id

string

The `deployment_id` that corresponds to this content.

persisted

boolean

400 -

401 -

403 -

404 -

Download the model definition model

GET /ml/v4/model_definitions/{model_definition_id}/model

Download the model definition model. It is possible to get the `model` for a given revision of the `model definition`. Model definitions for Deep Learning accept a zip file that contains one or more python files organized in any directory structure.

Auditing

Calling this method generates the following auditing event.

pm-20.model_definition.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 -

400 -

401 -

403 -

404 -

Create a new training definition

POST /ml/v4/training_definitions

Create a new training definition with the given payload. A training definition represents the training meta-data necessary to start a training job.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.create

Request

Request Body

training_definition_entity_request

Payload for creating the training definition. Either `space_id` or `project_id` has to be provided and is mandatory.

name

Required *

string

The name of the resource.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

experiment

Rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

pipeline

pipeline_rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

model_type

string

The underlying model type produced by the pipeline or by the model_definition.

data_bindings

array

The data bindings.

nodes_parameters

array

The node parameters.

hardware_spec

object

A hardware specification.

hybrid_pipeline_hardware_specs

array

Hybrid pipeline hardware specification.

model_definition

model_definition_rel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

rev

string

The revision of the referenced resource.

model_type

string

The underlying model type produced by the pipeline or by the model_definition.

hardware_spec

object

A hardware specification.

software_spec

object

A software specification.

command

string

If present, it overrides the command specified to the library resource itself.

parameters

object

Optional key-value pairs parameters.

federated_learning

Federated Learning.

model

object

The model type for federated_learning.

fusion_type

Required *

string

The fusion type for federated learning. For an in-depth description of each fusion type, please refer to here.

`iter_avg` - Simple Avg, simplest aggregation that is used as a baseline where all parties' model updates are equally weighted.
`avg` - Weighted Avg, weights the average of updates based on the number of each party sample. Use with training data sets of widely differing sizes.
`pfnm` - Probabilistic Federated Neural Matching (PFNM), communication-efficient method for fully connected neural networks when parties have heterogeneous data sets.
`spahm` - K-Means/SPAHM, used to train KMeans (unsupervised learning) models when parties have heterogeneous data sets.
`xgb_classifier` - XGBoost Classification, used to build classification models that use XGBoost.
`xgb_regressor` - XGBoost Regression, used to build regression models that use XGBoost.
`crypto_iter_avg` - Iterative averaging based fusion implemented with a crypto system.

remote_training

Required *

object

The remote training for federated learning.

rounds

integer

The number of training iterations to complete between the aggregator and the remote systems unless termination accuracy is achieved first.

termination_predicate

string

A boolean expression that describes the conditions, in terms of model metrics, under which training should complete.

epochs

integer

The total number of passes over the local training dataset to train a model.

optimizer

object

The optimizer for federated learning.

loss

string

The loss function to use in the boosting process.

metrics

string

The metrics for federated learning.

max_depth

integer

The maximum depth of each tree.

learning_rate

number

Controls how rapidly to change the model in response to the estimated error each time the model weights are updated.

l2_regularization

number

The coefficient for the L2 regularizer.

max_bins

integer

The maximum number of bins to use for non-missing values across all features.

max_leaf_nodes

integer

The maximum number of leaves for each tree.

min_samples_leaf

integer

The minimum number of samples per leaf.

random_state

integer

Seed used to set the pseudo-random number generator.

verbose

boolean

A general programming term to produce logging output

num_classes

integer

Number of target classes for the classification model.

byzantine_threshold

integer

Specifies the failure tolerance, for example the maximum number of parties that would possibly be failing during training.

sigma

number

Specifies how far the local model neurons are allowed from the global model.

sigma0

number

Specifies the standard deviation of the global network neurons.

gamma

number

Specifies the expected number of features present in each observation.

iters

integer

Specifies the number of iterations of randomly initialized matching-unmatching procedure is to be performed.

save_intermediate_models

boolean

If true, save the model generated at the end of each round of training.

crypto

object

Settings for cryptographic fusion for federated learning.

hardware_spec

object

A hardware specification.

software_spec

object

A software specification.

version

string

The version for federated learning.

log_level

string

The log level (`critical`, `error`, `warning`, `info`, `debug`) for federated learning.

sketch_accuracy_vs_privacy

number

training_data_references

array

Training datasets.

results_reference

Required *

object

The training results.

type

Required *

string

The data source type.

The possible types will depend on the API and platform being used.

location

Required *

object

Contains a set of fields that describe the location of the data with respect to the `connection`.

connection

object

Contains a set of fields specific to each connection. See here for details about specifying connections.

id

string

Item identification inside a collection, if appropriate.

test_data_references

array

The holdout/test datasets.

custom

Custom

User defined properties specified as key-value pairs.

Response

201 - Training definition created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity_common

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the training definitions

GET /ml/v4/training_definitions

Retrieve the training definitions for the specified space or project.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of training definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the training definition

GET /ml/v4/training_definitions/{training_definition_id}

Retrieve the training definition with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.read

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity_common

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the training definition

PATCH /ml/v4/training_definitions/{training_definition_id}

Update the training definition with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`
`/federated_learning`

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

200 - Training definition has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity_common

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the training definition

DELETE /ml/v4/training_definitions/{training_definition_id}

Delete the training definition with the specified identifier. This will delete all revisions of this training definition as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.delete

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

Response

204 - Training definition deleted

400 -

401 -

403 -

404 -

Create a new training definition revision

POST /ml/v4/training_definitions/{training_definition_id}/revisions

Create a new training definition revision. The current metadata and content for training_definition_id will be taken and a new revision created. Either `space_id` or `project_id` has to be provided and is mandatory.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.create

Request

Request Body

RevisionEntitySpaceProjectRequest

space_id

string

The space that contains the resource. Either `space_id` or `project_id` has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` has to be given.

commit_message

string

An optional commit message for the revision.

Response

201 - Training definition revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

training_resource_entity_common

The `training_data_references` contain the training datasets and the `results_reference` the connection where results will be stored.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the training definition revisions

GET /ml/v4/training_definitions/{training_definition_id}/revisions

Retrieve the training definition revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.training_definition.list

Request

Path Parameters

Query Parameters

space_id

string

The space that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

project_id

string

The project that contains the resource. Either `space_id` or `project_id` query parameter has to be given.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Training definition revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of training definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Create a new deployment job definition

POST /ml/v4/deployment_job_definitions

Create a new deployment job definition with the given payload. A deployment job definition represents the deployment metadata information in order to create a batch job in WML. This contains the same metadata used by the /ml/v4/deployment_jobs endpoint. This means that when submitting batch deployment jobs the user can either provide the job definition inline or reference a job definition in a query parameter.

Auditing

Calling this method generates the following auditing event.

pm-20.job.create

Request

Request Body

job_entity_request

Payload for creating the deployment job definition.

space_id

Required *

string

The space that contains the resource.

name

Required *

string

The name of the resource.

description

string

A description of the resource.

tags

Tags

A list of tags for this resource.

deployment

Required *

SimpleRel

A reference to a resource.

id

Required *

string

The id of the referenced resource.

custom

object

User defined properties.

hardware_spec

HardwareSpec

A hardware specification.

id

string

The id of the hardware specification.

rev

string

The revision of the hardware specification.

name

string

The name of the hardware specification.

num_nodes

integer

The number of nodes applied to a computation.

hybrid_pipeline_hardware_specs

Hybrid pipeline hardware specification.

scoring

job_scoring_request

Details about the input/output data and other properties to be used for a batch deployment job of a model, Python Function or a Python Scripts.

input_data

array

A list of payloads.

input_data_references

array

A list of input data references.

output_data_reference

object

A reference to data with an optional data schema. If necessary, it is possible to provide a data connection that contains just the data schema.

evaluations

array

A list of evaluation specifications.

environment_variables

object

This property is used to specify environment variables and their values required to be consumed by the batch deployment job. The environment variables and values must be specified as key-value pairs.

This property is currently supported only for Python Scripts in batch deployment jobs.

decision_optimization

job_decision_optimization_request

solve_parameters

object

To control solve behavior, you can specify solve parameters in your request as key-value pairs.

input_data

array

A list of payloads.

input_data_references

array

A list of input data references.

output_data

array

A list of output payloads.

output_data_references

array

A list of output data references.

Response

201 - Deployment job definition created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive. Specify only one of these when submitting a batch deployment job.

In case of output data references where the data asset is a remote database, users can specify if the batch deployment output must be appended to the table or if the table is to be truncated and output data updated. `output_data_references.location.write_mode` parameter can be used to for this purpose. The values `truncate` or `append` can be specified for `output_data_references.location.write_mode` parameter.

Specifying `truncate` as value will truncate the table and the batch output data will be inserted.
Specifying `append` as value will insert the batch output data to the remote database table.
The `write_mode` parameter is applicable only for `output_data_references` parameter.
The `write_mode` parameter will be applicable only for remote database related data assets. This parameter will not be applicable for local data asset or COS based data asset.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the deployment job definitions

GET /ml/v4/deployment_job_definitions

Retrieve the deployment job definitions for the specified space.

Auditing

Calling this method generates the following auditing event.

pm-20.job.list

Request

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

tag.value

string

Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.

search

string

These are the fields that can be searched in the `metadata`:

`/metadata/name`

Note that `tags` are filtered using the `tag` query parameter and the `tag` query parameter takes precedence over the `search` query parameter.

The metadata fields, on all assets, can be searched like this:

`/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`

The entity fields can be searched like this:

`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`

Response

200 - OK

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of deployment job definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the deployment job definition

GET /ml/v4/deployment_job_definitions/{job_definition_id}

Retrieve the deployment job definition with the specified identifier. If `rev` query parameter is provided, `rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record.

Auditing

Calling this method generates the following auditing event.

pm-20.job.read

Request

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

rev

string

The revision number of the resource.

Response

200 - OK

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive. Specify only one of these when submitting a batch deployment job.

In case of output data references where the data asset is a remote database, users can specify if the batch deployment output must be appended to the table or if the table is to be truncated and output data updated. `output_data_references.location.write_mode` parameter can be used to for this purpose. The values `truncate` or `append` can be specified for `output_data_references.location.write_mode` parameter.

Specifying `truncate` as value will truncate the table and the batch output data will be inserted.
Specifying `append` as value will insert the batch output data to the remote database table.
The `write_mode` parameter is applicable only for `output_data_references` parameter.
The `write_mode` parameter will be applicable only for remote database related data assets. This parameter will not be applicable for local data asset or COS based data asset.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Update the deployment job definition

PATCH /ml/v4/deployment_job_definitions/{job_definition_id}

Update the deployment job definition with the provided patch data. The following fields can be patched:

`/tags`
`/name`
`/description`
`/custom`
`/deployment`

Auditing

Calling this method generates the following auditing event.

pm-20.job.update

Request

Request Body

JsonPatch

Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

Response

200 - Deployment job definition has been patched successfully

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive. Specify only one of these when submitting a batch deployment job.

In case of output data references where the data asset is a remote database, users can specify if the batch deployment output must be appended to the table or if the table is to be truncated and output data updated. `output_data_references.location.write_mode` parameter can be used to for this purpose. The values `truncate` or `append` can be specified for `output_data_references.location.write_mode` parameter.

Specifying `truncate` as value will truncate the table and the batch output data will be inserted.
Specifying `append` as value will insert the batch output data to the remote database table.
The `write_mode` parameter is applicable only for `output_data_references` parameter.
The `write_mode` parameter will be applicable only for remote database related data assets. This parameter will not be applicable for local data asset or COS based data asset.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Delete the deployment job definition

DELETE /ml/v4/deployment_job_definitions/{job_definition_id}

Delete the deployment job definition with the specified identifier. This will delete all revisions of this deployment job definition as well. For each revision all attachments will also be deleted.

Auditing

Calling this method generates the following auditing event.

pm-20.job.delete

Request

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

Response

204 - Deployment job definition deleted

400 -

401 -

403 -

404 -

Create a new deployment job definition revision

POST /ml/v4/deployment_job_definitions/{job_definition_id}/revisions

Create a new deployment job definition revision. The current metadata and content for job_definition_id will be taken and a new revision created.

Auditing

Calling this method generates the following auditing event.

pm-20.job.create

Request

Request Body

revision_entity_space_request

space_id

Required *

string

The space that contains the resource.

commit_message

string

An optional commit message for the revision.

Response

201 - Deployment job definition revision created

metadata

ResourceMeta

Common metadata for a simple resource.

entity

job_entity

Details about the batch deployment job.

The `deployment` is a reference to the deployment associated with the deployment job or deployment job definition.

The `scoring` and `decision_optimization` properties are mutually exclusive. Specify only one of these when submitting a batch deployment job.

In case of output data references where the data asset is a remote database, users can specify if the batch deployment output must be appended to the table or if the table is to be truncated and output data updated. `output_data_references.location.write_mode` parameter can be used to for this purpose. The values `truncate` or `append` can be specified for `output_data_references.location.write_mode` parameter.

Specifying `truncate` as value will truncate the table and the batch output data will be inserted.
Specifying `append` as value will insert the batch output data to the remote database table.
The `write_mode` parameter is applicable only for `output_data_references` parameter.
The `write_mode` parameter will be applicable only for remote database related data assets. This parameter will not be applicable for local data asset or COS based data asset.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.

400 -

401 -

403 -

404 -

Retrieve the deployment job definition revisions

GET /ml/v4/deployment_job_definitions/{job_definition_id}/revisions

Retrieve the deployment job definition revisions.

Auditing

Calling this method generates the following auditing event.

pm-20.job.list

Request

Path Parameters

Query Parameters

space_id

Required *

string

The space that contains the resource.

start

string

Token required for token-based pagination. This token cannot be determined by end user. It is generated by the service and it is set in the href available in the `next` field.

limit

integer

How many resources should be returned. By default limit is 100. Max limit allowed is 200.

Response

200 - Deployment job definition revisions

total_count

integer

The total number of resources. Computed explicitly only when `total_count=true` query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

PaginationFirst

The reference to the first item in the current page.

PaginationNext

A reference to the first item of the next page, if any.

resources

array

A list of deployment job definitions.

system

SystemDetails

Optional details coming from the service and related to the API call or the associated resource.