Introduction to IBM watsonx.ai Runtime
Using IBM watsonx.ai Runtime, you can build analytic models and neural networks, trained with your own data, that you can deploy for use in applications. IBM watsonx.ai Runtime provides a full range of tools and services, so you can build, train, and deploy Machine Learning models. Choose from tools that fully automate the training process for rapid prototyping to tools that give you complete control to create a model that matches your needs.
For more information about how to use IBM watsonx.ai Runtime, see here.
There is a specialized python library that is available to access this REST API here.
Endpoint URLs
The following URL represents the base URLs for the IBM watsonx.ai Runtime API endpoints. When you call the API, use the URL and add the path for each method to form the complete API endpoint for your requests.
- Dallas:
https://us-south.ml.cloud.ibm.com - London -
https://eu-gb.ml.cloud.ibm.com - Frankfurt -
https://eu-de.ml.cloud.ibm.com - Tokyo -
https://jp-tok.ml.cloud.ibm.com - Sydney -
https://au-syd.ml.cloud.ibm.com
Example request to a Dallas endpoint:
curl -H "Authorization: Bearer {token}" -X {request_method} "https://us-south.ml.cloud.ibm.com/{method_endpoint}"
Replace {request_method}, and {method_endpoint} in this example with the values
for your particular API call. See the Authentication section below for more details about the bearer {token}.
Authentication
This API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests.
To work with the API, authenticate your application or service by including your IBM Cloud IAM access token in API requests.
IAM authentication. Replace {token} and {url}/{method} with your service credentials.
curl -H "Authorization:Bearer {token}" -X "{url}/{method}"
Authorization: Bearer {token}
For example, if the token is tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5 in the service credentials, include the credentials in your call like this:
curl -H "Authorization:Bearer tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5" -X "https://us-south.ml.cloud.ibm.com/ml/v4/models"
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.
| HTTP Code | Description | Recovery |
|---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete, or in the wrong format, or some other input validation failed. Be sure to include all required parameters in your request and check the request body. |
401 |
Unauthorized | You are not authorized to make this request. Log in and try again or provide a valid token. See Authenticating with IAM tokens for instructions on logging in. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized. |
404 |
Not Found | The requested resource could not be found. |
Additional headers
Some additional headers might be required to make successful requests to the API. Those additional headers are described below.
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to X-Global-Transaction-Id and the value is anything that you choose.
If there is not a transaction ID that is passed in, then one is generated randomly.
Versioning
API requests require a version parameter that takes a date in the format version=YYYY-MM-DD.
See API Handbook
for more details about date based API versioning.
When there is a change to the API in a backwards-incompatible way,
there will be a new version date published. Send the version parameter with every API request.
The service uses the API version for the date you specify or the most recent version before that date. It is not recommended defaulting to the current date. Instead, specify a date that matches a version that is compatible with your app and do not change it until your app is ready for a later version.
2021-05-01
The creation of deployment jobs is now fully asynchronous.
What this means is that the creation of the job will not return the platform_jobs section
in the response, instead poll the job using the deployment-jobs-get
operation until the platform_jobs section is provided in the response.
Data References
Accessing data in a remote location (such as a Cloud Object Storage bucket, or an SQL/no-SQL database) requires
the use of connection_asset or data_asset reference types.
These reference types are created within a space or a project and are referenced in WML requests to represent input
data and results locations. These types contain two parameter objects, connection and location, which require
different values to be supplied based on the reference type. Using a data_asset, requires an href to be supplied
to the location object whereas using a connection_asset requires the connection_id for the connection object
and different location fields depending on the data source type, see
Data reference Description
for details.
Example data_asset payload:
{
"training_data_references": [
{
"type": "data_asset",
"location": {
"href": "/v2/assets/<asset_id>?space_id=<space_id>"
}
}
]
}
Example connection_asset payload:
{
"training_data_references": [
{
"type": "connection_asset",
"connection": {
"id": "<connection_guid>"
},
"location": {
"<wdp-properties depending on the type>": "..."
}
}
]
}
Example url payload (Decision Optimization only):
{
"training_data_references": {
"type": "url",
"id": "diet_food.csv",
"connection": {
"verb": "GET",
"url": "https://myserver.com/diet_food.csv",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
}
},
"location": {
}
}
}
Activity Tracker events
You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.
For more information about how to track IBM watsonx.ai Runtime activity, see Auditing events for IBM watsonx.ai Runtime.
Methods
Create a new WML deployment
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.
POST /ml/v4/deployments
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The deployment entity.
The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fUser defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
A reference to a resource.
A hardware specification.
Hybrid pipeline hardware specification.
Indicates that this is an online deployment. An empty object has to be specified. If the online scoring schema has a
typeofDataFramethen the scoring payload will be converted to aPandasdata frame.Indicates that this is a batch deployment. An empty object has to be specified.
Tags that can be used when searching for resources.
Examples:[ "dev", "TF" ]The name of the deployment.
Example:
customer_churnA description of the deployment.
Example:
Customer churn prediction model deployment
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployments?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "tags": [ "dev", "TF" ], "name": "customer_churn", "description": "Customer churn prediction model deployment", "custom": "<object>", "asset": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2" }, "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "hybrid_pipeline_hardware_specs": [ { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } }, { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } } ], "online": { "parameters": "<object>" }, "batch": { "parameters": "<object>" }, "r_shiny": { "authentication": "members_of_deployment_space", "parameters": "<object>" }, }'
Response
A deployment resource.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of the deployment.
Status Code
Deployment created.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the deployments
Retrieve the list of deployments for the specified space.
GET /ml/v4/deployments
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieves the deployments that belong to this space.
Example:
2ae804f8-fa85-4106-8228-cbc7e408ad79Retrieves the deployment, if any, that contains this
serving_name.Example:
churnRetrieves only the resources with the given tag value.
Retrieves only the resources with the given asset_id, asset_id would be either model_id or function_id.
Retrieves only the resources with the given name.
Retrieves the resources filtered with the given type. Allowed values are
model,function,py_scriptanddo.Retrieves the resources filtered by state. Allowed values are
initializing,updating,readyandfailed.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'.
Returns whether serving_name is available for use or not. This query parameter cannot be combined with any other except for 'serving_name'.
Default:
false
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployments?space_id=<string>&tag.value=<string>&asset_id=<string>&version=2020-09-01'
Response
The deployment resources.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of deployment resources. This will be empty if 'stats' query parameter is passed with 'true'.
System details including warnings and stats. This will get populated only if 'stats' query parameter is passed with 'true'.
- system
Optional details provided by the service about statistics of the number of deployments created. The deployments that are counted will depend on the request parameters.
Status Code
OK.
serving_name is available for use. Returned when serving_name and conflict query parameters are used.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
Returned when serving_name and conflict query parameters are used. The response body will contain the reason.
No Sample Response
Retrieve the deployment details
Retrieve the deployment details with the specified identifier.
GET /ml/v4/deployments/{deployment_id}Request
Path Parameters
The deployment id.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieves the deployments of assets that belong to this space.
Example:
2ae804f8-fa85-4106-8228-cbc7e408ad79
curl --request GET "{url}/v4/deployments/{deployment_id}"
Response
A deployment resource.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of the deployment.
Status Code
Deployment details.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the deployment
Delete the deployment with the specified identifier.
DELETE /ml/v4/deployments/{deployment_id}Request
Path Parameters
The deployment id.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieves the deployments of assets that belong to this space.
Example:
2ae804f8-fa85-4106-8228-cbc7e408ad79
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/deployments/:deployment_id?space_id=<string>&version=2020-09-01'
Update the deployment metadata
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/parametersIn 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 inhardware_spec.num_nodesparameter. Ashardware_spec.nameorhardware_spec.idis mandatory forhardware_specschema, a valid value such asXS,Smust be specified forhardware_spec.nameparameter as part of PATCH request. Alternatively, users can also specify a valid ID of a hardware specification inhardware_spec.idparameter. However, changes related tohardware_spec.nameorhardware_spec.idspecified 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 eitherhardware_spec.nameorhardware_spec.idof the hardware specification that suits their requirement. In the batch deployment context,hardware_spec.num_nodesparameter is not currently supported.
When 'asset' is patched with id/rev:- Deployment with the patched id/rev is started. - With an asynchronous deployment (
versiongreater 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.
PATCH /ml/v4/deployments/{deployment_id}Request
Path Parameters
The deployment id.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieves the deployments of assets that belong to this space.
Example:
2ae804f8-fa85-4106-8228-cbc7e408ad79
The json patch.
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/deployments/:deployment_id?space_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
A deployment resource.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of the deployment.
Status Code
Deployment accepted
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Execute a synchronous deployment prediction
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.
POST /ml/v4/deployments/{deployment_id}/predictionsRequest
Path Parameters
The
deployment_idcan be either thedeployment_idthat identifies the deployment or aserving_namethat allows a predefined URL to be used to post a prediction.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The scoring data.
The input data.
Parameters that can be used to control the prediction request.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployments/:deployment_id/predictions?version=2020-09-01' --data-raw '{ "input_data": [ { "id": "<string>", "fields": [ "<string>", "<string>" ], "values": [ [ "<object>", "<object>" ], [ "<object>", "<object>" ] ] }, { "id": "<string>", "fields": [ "<string>", "<string>" ], "values": [ [ "<object>", "<object>" ], [ "<object>", "<object>" ] ] } ] }'
Retrieve the 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.
GET /ml/v4/deployment_jobs
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieves the deployment jobs that belong to this space.
Retrieves only the jobs with these tags (comma separated).
Filter based on on the deployment job state: queued, running, completed, failed etc.
Filter based on the deployment_id.
Retrieves only fields from
decision_optimizationandscoringsection mentioned as comma separated values as output response fields. Retrieves all the fields if not mentioned.
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_jobs?space_id=<string>&tag.value=<string>&state=<string>&deployment_id=<string>&version=2020-09-01'
Response
The information related to the jobs.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of jobs.
Status Code
Jobs response.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Start an asynchronous deployment job
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.
POST /ml/v4/deployment_jobs
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Defines 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.
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
truncateas value will truncate the table and the batch output data will be inserted. - Specifying
appendas value will insert the batch output data to the remote database table. - The
write_modeparameter is applicable only foroutput_data_referencesparameter. - The
write_modeparameter 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.
The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe name of the resource.
Example:
my-resourceA reference to a resource.
A description of the resource.
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_jobs?version=2020-09-01' --data-raw '{ "space_id":"3fc54cf1-252f-424b-b52d-5cdd9814987f", "name":"my-resource", "deployment":{ "id":"4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "hardware_spec":{ "id":"4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev":"2", "name":"string", "num_nodes":2 }, "scoring":{ "input_data":[ { "id":"string", "type":"target", "fields":[ "string" ], "values":[ [ { } ] ], "targets":[ [ { } ] ] } ], "output_data_reference":{ "id":"string", "type":"s3", "connection":{ } }, "evaluations":[ { "id":"string", "input_target":"string", "metrics_names":[ "auroc", "accuracy" ] } ] } }' echo "DO Payload Example" curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_jobs?version=2020-09-01' --data-raw '{ "name":"test-job", "space_id":"dcfb2ae2-1733-11ec-9621-0242ac130002", "deployment":{ "id":"e672c9e0-1733-11ec-9621-0242ac130002" }, "decision_optimization":{ "solve_parameters":{ "oaas.logAttachmentName":"log.txt", "oaas.logTailEnabled":"true" }, "input_data":[ { "id": "data.bin", "content": "VGhlIGNvbnRlbnQgb2YgbXkgZGF0YSBmaWxlLgo=" }, { "id": "tuples.csv", "fields": ["Name", "Value"], "values": [ ["name1", 1], ["name2", 11934] ]} }, ], "input_data_references":[ { "id":"c1.mod", "type":"data_asset", "location":{ "href":"/v2/assets/ec45babc-1733-11ec-9621-0242ac130002?space_id=dcfb2ae2-1733-11ec-9621-0242ac130002" } } ], "output_data":[ { "id":".*\\.*" } ] }'
Response
The information related to the job.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information about the platform job assets related to this execution.
Status Code
Accepted
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Cancel the deployment job
Cancel the specified deployment job.
DELETE /ml/v4/deployment_jobs/{job_id}Request
Path Parameters
The id of the job.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Cancel the deployment job that belong to this space.
Set to true in order to also delete the job metadata information.
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_jobs/:job_id?space_id=<string>&hard_delete=<boolean>&version=2020-09-01'
Retrieve the deployment job
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.
GET /ml/v4/deployment_jobs/{job_id}Request
Path Parameters
The id of the job.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Retrieve the deployment job that belong to this space.
Retrieves only fields from
decision_optimizationandscoringsection mentioned as comma separated values as output response fields. Retrieves all the fields if not mentioned.
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_jobs/:job_id?space_id=<string>&version=2020-09-01'
Response
The information related to the job.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information about the platform job assets related to this execution.
Status Code
Jobs response.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Create a new deployment job definition
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.
POST /ml/v4/deployment_job_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the deployment job definition.
The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe name of the resource.
Example:
my-resourceA reference to a resource.
A description of the resource.
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "name": "my-resource", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "deployment": { "value": "<Error: Too many levels of nesting to fake this schema>" }, "custom": { "value": "<Error: Too many levels of nesting to fake this schema>" }, "hardware_spec": { "value": "<Error: Too many levels of nesting to fake this schema>" }, "hybrid_pipeline_hardware_specs": { "value": "<Error: Too many levels of nesting to fake this schema>" }, "scoring": { "value": "<Error: Too many levels of nesting to fake this schema>" }, "decision_optimization": { "value": "<Error: Too many levels of nesting to fake this schema>" } }'
Response
The information for a deployment job definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }- metadata
The id of the resource.
The time when the resource was created.
The revision of the resource.
The user id which created this resource.
The time when the resource was last modified.
The id of the parent resource where applicable.
The name of the resource.
A description of the resource.
A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]Information related to the revision.
The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987f
Details about the batch deployment job.
The
deploymentis a reference to the deployment associated with the deployment job or deployment job definition.The
scoringanddecision_optimizationproperties are mutually exclusive. Specify only one of these when submitting a batch deployment job.Use
hybrid_pipeline_hardware_specsonly in a batch deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other cases usehardware_specto 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.
output_data_references.location.write_modeparameter can be used to for this purpose. The valuestruncateorappendcan be specified foroutput_data_references.location.write_modeparameter.- Specifying
truncateas value will truncate the table and the batch output data will be inserted. - Specifying
appendas value will insert the batch output data to the remote database table. - The
write_modeparameter is applicable only foroutput_data_referencesparameter. - The
write_modeparameter 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.
- entity
A reference to a resource.
User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
- Specifying
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Deployment job definition created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the deployment job definitions
Retrieve the deployment job definitions for the specified space.
GET /ml/v4/deployment_job_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions?space_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of deployment job definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of deployment job definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the deployment job definition
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.
GET /ml/v4/deployment_job_definitions/{job_definition_id}Request
Path Parameters
Deployment job definition identifier.
Example:
212fadf1-252f-424b-b52d-5cdd98ecfa0
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions/:job_definition_id?space_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for a deployment job definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }- metadata
The id of the resource.
The time when the resource was created.
The revision of the resource.
The user id which created this resource.
The time when the resource was last modified.
The id of the parent resource where applicable.
The name of the resource.
A description of the resource.
A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]Information related to the revision.
The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987f
Details about the batch deployment job.
The
deploymentis a reference to the deployment associated with the deployment job or deployment job definition.The
scoringanddecision_optimizationproperties are mutually exclusive. Specify only one of these when submitting a batch deployment job.Use
hybrid_pipeline_hardware_specsonly in a batch deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other cases usehardware_specto 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.
output_data_references.location.write_modeparameter can be used to for this purpose. The valuestruncateorappendcan be specified foroutput_data_references.location.write_modeparameter.- Specifying
truncateas value will truncate the table and the batch output data will be inserted. - Specifying
appendas value will insert the batch output data to the remote database table. - The
write_modeparameter is applicable only foroutput_data_referencesparameter. - The
write_modeparameter 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.
- entity
A reference to a resource.
User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
- Specifying
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the deployment job definition
Update the deployment job definition with the provided patch data. The following fields can be patched:
/tags/name/description/custom/deployment
PATCH /ml/v4/deployment_job_definitions/{job_definition_id}Request
Path Parameters
Deployment job definition identifier.
Example:
212fadf1-252f-424b-b52d-5cdd98ecfa0
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions/:job_definition_id?space_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a deployment job definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }- metadata
The id of the resource.
The time when the resource was created.
The revision of the resource.
The user id which created this resource.
The time when the resource was last modified.
The id of the parent resource where applicable.
The name of the resource.
A description of the resource.
A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]Information related to the revision.
The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987f
Details about the batch deployment job.
The
deploymentis a reference to the deployment associated with the deployment job or deployment job definition.The
scoringanddecision_optimizationproperties are mutually exclusive. Specify only one of these when submitting a batch deployment job.Use
hybrid_pipeline_hardware_specsonly in a batch deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other cases usehardware_specto 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.
output_data_references.location.write_modeparameter can be used to for this purpose. The valuestruncateorappendcan be specified foroutput_data_references.location.write_modeparameter.- Specifying
truncateas value will truncate the table and the batch output data will be inserted. - Specifying
appendas value will insert the batch output data to the remote database table. - The
write_modeparameter is applicable only foroutput_data_referencesparameter. - The
write_modeparameter 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.
- entity
A reference to a resource.
User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
- Specifying
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Deployment job definition has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the deployment job definition
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.
DELETE /ml/v4/deployment_job_definitions/{job_definition_id}Request
Path Parameters
Deployment job definition identifier.
Example:
212fadf1-252f-424b-b52d-5cdd98ecfa0
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions/:job_definition_id?space_id=<string>&version=2020-09-01'
Create a new deployment job definition revision
Create a new deployment job definition revision. The current metadata and content for job_definition_id will be taken and a new revision created.
POST /ml/v4/deployment_job_definitions/{job_definition_id}/revisionsRequest
Path Parameters
Deployment job definition identifier.
Example:
212fadf1-252f-424b-b52d-5cdd98ecfa0
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions/:job_definition_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a deployment job definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }- metadata
The id of the resource.
The time when the resource was created.
The revision of the resource.
The user id which created this resource.
The time when the resource was last modified.
The id of the parent resource where applicable.
The name of the resource.
A description of the resource.
A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]Information related to the revision.
The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987f
Details about the batch deployment job.
The
deploymentis a reference to the deployment associated with the deployment job or deployment job definition.The
scoringanddecision_optimizationproperties are mutually exclusive. Specify only one of these when submitting a batch deployment job.Use
hybrid_pipeline_hardware_specsonly in a batch deployment job of a hybrid pipeline in order to specify compute configuration for each pipeline node. For all other cases usehardware_specto 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.
output_data_references.location.write_modeparameter can be used to for this purpose. The valuestruncateorappendcan be specified foroutput_data_references.location.write_modeparameter.- Specifying
truncateas value will truncate the table and the batch output data will be inserted. - Specifying
appendas value will insert the batch output data to the remote database table. - The
write_modeparameter is applicable only foroutput_data_referencesparameter. - The
write_modeparameter 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.
- entity
A reference to a resource.
User defined properties.
A hardware specification.
Hybrid pipeline hardware specification.
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_dataproperty to specify the input data for batch processing as part of the job's payload. Theinput_dataproperty is mutually exclusive withinput_data_referencesproperty, only use one of these. Wheninput_datais specified, the processed output of batch deployment job will be available inscoring.predictionsparameter in the deployment job response.input_dataproperty is not supported for batch deployment of Python Scripts.Use
input_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available. Theinput_data_referencesmust be used withoutput_data_references. Theinput_data_referencesproperty is mutually exclusive withinput_dataproperty, only use one of these. Theinput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.Use
output_data_referencesproperty to specify the details pertaining to the remote source where the input data for batch deployment job is available.output_data_referencesmust be used withinput_data_references. Theoutput_data_referencesproperty is not supported for batch deployment job of Spark models and Python Functions.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_parametersas named value pairs to control the Decision Optimization solve behavior. Use theinput_dataandoutput_dataproperties to specify respectively input and output data for batch processing as part of the job's payload. Use theinput_data_referencesandoutput_data_referencesproperties to specify respectively input and output data for batch processing as remote data sources.
- Specifying
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Deployment job definition revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the deployment job definition revisions
Retrieve the deployment job definition revisions.
GET /ml/v4/deployment_job_definitions/{job_definition_id}/revisionsRequest
Path Parameters
Deployment job definition identifier.
Example:
212fadf1-252f-424b-b52d-5cdd98ecfa0
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource.
Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/deployment_job_definitions/:job_definition_id/revisions?space_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of deployment job definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of deployment job definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Deployment job definition revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Create a new experiment
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.
POST /ml/v4/experiments
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the experiment. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]The label column.
The optional evaluation definition.
The optional training references used by the experiment.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments?version=2020-09-01' --data-raw '{ "name": "my-resource", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "label_column": "<string>", "evaluation_definition": { "metrics": [ { "name": "<string>", "maximize": "<boolean>" }, { "name": "<string>", "maximize": "<boolean>" } ], "method": "binary" }, "training_references": [ { "pipeline": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "data_bindings": [ { "data_reference_name": "<string>", "node_id": "<string>" }, { "data_reference_name": "<string>", "node_id": "<string>" } ], "nodes_parameters": [ { "node_id": "<string>", "parameters": "<object>" }, { "node_id": "<string>", "parameters": "<object>" } ], "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "hybrid_pipeline_hardware_specs": [ { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } }, { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } } ] }, "model_definition": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "hyper_parameters_optimization": { "method": { "name": "random", "parameters": "<object>" }, "hyper_parameters": [ { "name": "learning_rate", "items": [ 0.005, 0.1, 0.11 ] }, { "name": "fc", "items": { "min_value": 9, "max_value": 10, "power": 2 } } ] } }, { "pipeline": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "data_bindings": [ { "data_reference_name": "<string>", "node_id": "<string>" }, { "data_reference_name": "<string>", "node_id": "<string>" } ], "nodes_parameters": [ { "node_id": "<string>", "parameters": "<object>" }, { "node_id": "<string>", "parameters": "<object>" } ], "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "hybrid_pipeline_hardware_specs": [ { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } }, { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } } ] }, "model_definition": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "hyper_parameters_optimization": { "method": { "name": "random", "parameters": "<object>" }, "hyper_parameters": [ { "name": "learning_rate", "items": [ 0.005, 0.1, 0.11 ] }, { "name": "fc", "items": { "min_value": 9, "max_value": 10, "power": 2 } } ] } } ], "custom": "<object>" }'
Response
The information for an experiment.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the experiment to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Experiment created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the experiments
Retrieve the experiments for the specified space or project.
GET /ml/v4/experiments
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of experiments.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of experiments.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the experiment
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.
GET /ml/v4/experiments/{experiment_id}Request
Path Parameters
Experiment identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments/:experiment_id?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for an experiment.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the experiment to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the experiment
Update the experiment with the provided patch data. The following fields can be patched:
/tags/name/description/custom
PATCH /ml/v4/experiments/{experiment_id}Request
Path Parameters
Experiment identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments/:experiment_id?space_id=<string>&project_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for an experiment.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the experiment to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Experiment has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the experiment
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.
DELETE /ml/v4/experiments/{experiment_id}Request
Path Parameters
Experiment identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments/:experiment_id?space_id=<string>&project_id=<string>&version=2020-09-01'
Create a new experiment revision
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.
POST /ml/v4/experiments/{experiment_id}/revisionsRequest
Path Parameters
Experiment identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments/:experiment_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for an experiment.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the experiment to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Experiment revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the experiment revisions
Retrieve the experiment revisions.
GET /ml/v4/experiments/{experiment_id}/revisionsRequest
Path Parameters
Experiment identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/experiments/:experiment_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of experiments.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of experiments.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Experiment revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Create a new function
Create a new function with the given payload. A function is some code that can be deployed as an online, or batch deployment.
POST /ml/v4/functions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the function. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceA software specification.
The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]Type of the function to be created. Only
pythontype is supported as of now. If not specified,pythonis 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 scoreDefault:
pythonExample:
pythonScoring data.
The schemas of the expected data.
- schemas
The schema of the expected input data.
The schema of the expected output data.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
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.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/functions?version=2020-09-01' --data-raw '{ "name": "my-resource", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "software_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "..." }, "type": "python", "sample_scoring_input": { "input_data": [ { "id": "<string>", "fields": [ { "name", "age", "occupation" { ], "values": [ [ "<object>", "<object>" ], [ "<object>", "<object>" ] ] }, { "id": "<string>", "fields": [ { "name", "age", "occupation" { ], "values": [ [ "<object>", "<object>" ], [ "<object>", "<object>" ] ] } ] }, "schemas": { "input": [ { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" }, { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } ], "output": [ { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" }, { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } ] }, "custom": "<object>" }'
Response
The information for a function.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the function to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Function created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the functions
Retrieve the functions for the specified space or project.
GET /ml/v4/functions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/functions?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of functions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of functions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the function
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.
GET /ml/v4/functions/{function_id}Request
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for a function.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the function to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the function
Update the function with the provided patch data. The following fields can be patched:
/tags/name/description/custom
PATCH /ml/v4/functions/{function_id}Request
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id?space_id=<string>&project_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a function.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the function to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Function has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the function
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.
DELETE /ml/v4/functions/{function_id}Request
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id?space_id=<string>&project_id=<string>&version=2020-09-01'
Create a new function revision
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.
POST /ml/v4/functions/{function_id}/revisionsRequest
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a function.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the function to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Function revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the function revisions
Retrieve the function revisions.
GET /ml/v4/functions/{function_id}/revisionsRequest
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of functions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of functions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Function revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Upload the function 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:
...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
PUT /ml/v4/functions/{function_id}/codeRequest
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
A gzip file containing code files.
curl --request PUT 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id/code?space_id=<string>&project_id=<string>&version=2020-09-01'
Response
The metadata related to the attachment.
The content id for the attachment.
Example:
fd45606f-8098-459c-8961-32b136123fgcThe type of the content.
Example:
nativeThe name of the attachment.
Example:
my_attachmentThe
pipeline_node_idthat corresponds to this content.Example:
fg094cf1-252f-424b-b52d-5cdd981a981eThe
deployment_idthat corresponds to this content.Example:
12345cf1-252f-424b-b52d-5cdd981a1234This will be set to
trueif 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 thewarningsfield of thesystem_detailsthat are returned with the model details.Example:
true
Status Code
Function code uploaded
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Download the function 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:
...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
GET /ml/v4/functions/{function_id}/codeRequest
Path Parameters
Function identifier.
Example:
64dc8921-345f-234b-462d-78e41246987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/functions/:function_id/code?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Retrieve the service instances
Retrieve the service instances. Either space_id or project_id query parameter is mandatory but both can be provided.
GET /ml/v4/instances
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Return resources pertaining to any space_id listed. Either
space_idorproject_idquery parameter is mandatory but both can be provided.Return resources pertaining to any project_id listed. Either
space_idorproject_idquery parameter is mandatory but both can be provided.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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Only if
consumption_detailsis set totrueeach instanceentity.consumption.detailspart is available in response.Default:
falseExample:
true
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/instances?space_id=<string>,<string>&project_id=<string>,<string>&start=<string>&limit=100&version=2020-09-01'
Response
Information for paging when querying resources.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
Status Code
OK.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the service instance
Retrieve the service instance details.
GET /ml/v4/instances/{instance_id}Request
Path Parameters
The instance identifier.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Defines authorization context that allows a space member to perform this operation.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fDefines authorization context that allows a project member to perform this operation.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fOnly if
consumption_detailsis set totruethe instanceentity.consumption.detailspart is available in response.Default:
falseExample:
true
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/instances/:instance_id?space_id=63dc4cf1-252f-424b-b52d-5cdd9814987f&project_id=63dc4cf1-252f-424b-b52d-5cdd9814987f&version=2020-09-01'
Response
Common metadata for a resource.
Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }
Status Code
OK.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Create a new model
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.
POST /ml/v4/models
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
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.
curated_model
A curated model example.
{
"type": "curated_foundation_model_1.0",
"name": "my-flan-t5-xl",
"space_id": "37c69d0e-a2c2-413b-bd27-a03c15967b2f",
"foundation_model": {
"model_id": "ibm/granite-13b-chat-v2-curated"
}
}The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe model type. The supported model types can be found in the documentation here.
Example:
tensorflow_1.5The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]A software specification.
A reference to a resource.
The model definition.
Hyper parameters used for training this model.
User provided domain name for this model. For example: sentiment, entity, visual-recognition, finance, retail, real estate etc.
The training data that was used to create this model.
The holdout/test datasets.
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.
- schemas
The schema of the expected prediction input data, see datarecord-metadata-v2-schema for the schema definition.
The schema of the expected prediction output data, see datarecord-metadata-v2-schema for the schema definition.
The name of the label column.
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_columnin the initial data set.This will be used by scoring to record the size of the model.
- size
The memory size of the model.
The size of the model on disk.
Metrics that can be returned by an operation.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
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
keyand its fully qualified class or function name must be specified as thevalue. This is applicable forTensorflow 2.Xmodels serialized inH5format using thetf.kerasAPI.Examples:{ "MyLayer": "my_layers.MyLayer" }- user_defined_objects
The list of the software specifications that are used by the pipeline that generated this model, if the model was generated by a pipeline.
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.
- model_version
This is the user-provided version which should follow semantic versioning.
Example:
1.0.0This is the user-provided tag for the model.
Example:
xgb classifierThis is the user provided description that provides context for the change in the model version.
Example:
Providing an update to the version.
Deprecated: this is replaced by
training.id. This field can be used to store theidof the training job that was used to produce this model.Example:
b8e64f4b-ead1-47f3-abf6-8247b2826763An optional array which contains the data preprocessing transformations that were executed by the training job that created this model.
Examples:{ "data_preprocessing": [ { "stage": "sampling", "input": { "rows": 100800, "columns": 3 }, "output": { "rows": 80000, "columns": 3 }, "props": { "type": "truncate" } }, { "stage": "cleansing", "input": { "rows": 80000, "columns": 3 }, "output": { "rows": 79987, "columns": 3 }, "props": { "outliers_count": 23, "duplicated_rows_count": 13 } } ] }Information about the training job that created this model.
Details about the attachments that should be uploaded with this model.
Response
The information for a model.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information related to the upload of the model content.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model created
Model accepted, this is returned in the case that
content_locationwas 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 thecontent_import_statein the model status (/ml/v4/models/{model_id}) iscompleted.Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&software_spec=<string>&version=2024-10-17'
Response
A paginated list of models.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of models.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the model
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.
GET /ml/v4/models/{model_id}Request
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id?space_id=<string>&project_id=<string>&rev=<string>&version=2024-10-17'
Response
The information for a model.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information related to the upload of the model content.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the model
Update the model with the provided patch data. The following fields can be patched:
/tags/name/description/custom/software_spec(operationreplaceonly)/model_version(operationaddandreplaceonly)
PATCH /ml/v4/models/{model_id}Request
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id?space_id=<string>&project_id=<string>&version=2024-10-17' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a model.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information related to the upload of the model content.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the model
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.
DELETE /ml/v4/models/{model_id}Request
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id?space_id=<string>&project_id=<string>&version=2024-10-17'
Create a new model revision
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.
POST /ml/v4/models/{model_id}/revisionsRequest
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/revisions?version=2024-10-17' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a model.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }Information related to the upload of the model content.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Request
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2024-10-17'
Response
A paginated list of models.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of models.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the model content metadata list
Retrieve the content metadata list for the specified model attachments.
GET /ml/v4/models/{model_id}/contentRequest
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2List only attachments with the given name.
Example:
my_modelThis 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.
Example:
native
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/content?space_id=<string>&project_id=<string>&rev=<string>&name=<string>&content_format=<string>&version=2024-10-17'
Response
The metadata related to the attachments.
The number of attachments associated with the resource.
Example:
1The metadata related to the attachment.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Upload the model content
Upload the content for the specified model.
PUT /ml/v4/models/{model_id}/contentRequest
Custom Headers
Allowable values: [
application/zip,application/json,text/plain,application/xml]
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07This 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.
Example:
nativeThe space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcReturns only resources that match this
pipeline_node_id, this is only relevant ifcontent_formatispipeline-node.Example:
62344cf1-252f-424b-b52d-5cdd9814aacdReturns only resources that match this
deployment_id, this is only relevant ifcontent_formatiscoreml.Example:
62344cf1-252f-424b-b52d-5cdd9814aacdProvide the name of the attachment.
Example:
my_models
models file
curl --request PUT 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/content?content_format=<string>&space_id=<string>&project_id=<string>&pipeline_node_id=<string>&name=<string>&version=2024-10-17' --data-raw '"<object>"'
Response
The metadata related to the attachment.
The content id for the attachment.
Example:
fd45606f-8098-459c-8961-32b136123fgcThe type of the content.
Example:
nativeThe name of the attachment.
Example:
my_attachmentThe
pipeline_node_idthat corresponds to this content.Example:
fg094cf1-252f-424b-b52d-5cdd981a981eThe
deployment_idthat corresponds to this content.Example:
12345cf1-252f-424b-b52d-5cdd981a1234This will be set to
trueif 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 thewarningsfield of thesystem_detailsthat are returned with the model details.Example:
true
Status Code
Model content uploaded
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Download the model content
Download the model content.
GET /ml/v4/models/{model_id}/content/{attachment_id}Request
Custom Headers
Allowable values: [
application/zip,application/gzip,application/json,text/plain,application/xml]
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fIdentifier for the attachment for resources that support separate content.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/content/:attachment_id?space_id=<string>&project_id=<string>&rev=<string>&version=2024-10-17'
Delete the model content
Delete the content for the specified model.
DELETE /ml/v4/models/{model_id}/content/{attachment_id}Request
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fIdentifier for the attachment for resources that support separate content.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/content/:attachment_id?space_id=<string>&project_id=<string>&version=2024-10-17'
Download the model content that matches a certain criteria
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.
GET /ml/v4/models/{model_id}/downloadRequest
Custom Headers
Allowable values: [
application/zip,application/gzip,application/json,text/plain,application/xml]
Path Parameters
Model identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2Returns only resources that match this
pipeline_node_id, this is only relevant ifcontent_formatispipeline-node.Example:
62344cf1-252f-424b-b52d-5cdd9814aacdReturns only resources that match this
deployment_id, this is only relevant ifcontent_formatiscoreml.Example:
62344cf1-252f-424b-b52d-5cdd9814aacdMatch an attachment with this name.
Example:
my_modelThis 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.
Example:
native
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/models/:model_id/download?space_id=<string>&project_id=<string>&rev=<string>&pipeline_node_id=<string>&name=<string>&content_format=<string>&version=2024-10-17'
Create a new model definition
Create a new model definition with the given payload. A model definition represents the code that is used to train one or more models.
POST /ml/v4/model_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the model definition. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe package version.
- platform
The name of the platform.
The supported versions.
The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]The command used to run the model.
A software specification.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions?version=2020-09-01' --data-raw '{ "name": "my-resource", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "version": "<string>", "platform": { "name": "<string>", "versions": [ "<string>", "<string>" ] }, "command": "<string>", "custom": "<object>" }'
Response
The information for a model definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a model. The
software_specis used only for training. Either space_id or project_id has to be provided and is mandatory.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model definition created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the model definitions
Retrieve the model definitions for the specified space or project.
GET /ml/v4/model_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of model definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of model definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the model definition
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.
GET /ml/v4/model_definitions/{model_definition_id}Request
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for a model definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a model. The
software_specis used only for training. Either space_id or project_id has to be provided and is mandatory.Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the model definition
Update the model definition with the provided patch data. The following fields can be patched:
/tags/name/description/custom
PATCH /ml/v4/model_definitions/{model_definition_id}Request
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id?space_id=<string>&project_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a model definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a model. The
software_specis used only for training. Either space_id or project_id has to be provided and is mandatory.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model definition has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the model definition
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.
DELETE /ml/v4/model_definitions/{model_definition_id}Request
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id?space_id=<string>&project_id=<string>&version=2020-09-01'
Create a new model definition revision
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.
POST /ml/v4/model_definitions/{model_definition_id}/revisionsRequest
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a model definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a model. The
software_specis used only for training. Either space_id or project_id has to be provided and is mandatory.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model definition revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the model definition revisions
Retrieve the model definition revisions.
GET /ml/v4/model_definitions/{model_definition_id}/revisionsRequest
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of model definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of model definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Model definition revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Upload the model definition 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.
PUT /ml/v4/model_definitions/{model_definition_id}/modelRequest
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
A gzip file containing code files.
curl --request PUT 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id/model?space_id=<string>&project_id=<string>&version=2020-09-01'
Response
The metadata related to the attachment.
The content id for the attachment.
Example:
fd45606f-8098-459c-8961-32b136123fgcThe type of the content.
Example:
nativeThe name of the attachment.
Example:
my_attachmentThe
pipeline_node_idthat corresponds to this content.Example:
fg094cf1-252f-424b-b52d-5cdd981a981eThe
deployment_idthat corresponds to this content.Example:
12345cf1-252f-424b-b52d-5cdd981a1234This will be set to
trueif 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 thewarningsfield of thesystem_detailsthat are returned with the model details.Example:
true
Status Code
Model definition model uploaded
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Download the model definition 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.
GET /ml/v4/model_definitions/{model_definition_id}/modelRequest
Path Parameters
Model definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/model_definitions/:model_definition_id/model?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Create a new pipeline
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.
POST /ml/v4/pipelines
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the pipeline. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe pipeline document, see pipeline-flow-v2-schema for the schema definition.
The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines?version=2020-09-01' --data-raw '{ "name": "my-resource", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "document": "<object>", "custom": "<object>" }'
Response
The information for a pipeline.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the pipeline to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Pipeline created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the pipelines
Retrieve the pipelines for the specified space or project.
GET /ml/v4/pipelines
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of pipelines.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of pipelines.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the pipeline
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.
GET /ml/v4/pipelines/{pipeline_id}Request
Path Parameters
Pipeline identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines/:pipeline_id?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for a pipeline.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the pipeline to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the pipeline
Update the pipeline with the provided patch data. The following fields can be patched:
/tags/name/description/custom
PATCH /ml/v4/pipelines/{pipeline_id}Request
Path Parameters
Pipeline identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines/:pipeline_id?space_id=<string>&project_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a pipeline.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the pipeline to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Pipeline has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the pipeline
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.
DELETE /ml/v4/pipelines/{pipeline_id}Request
Path Parameters
Pipeline identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines/:pipeline_id?space_id=<string>&project_id=<string>&version=2020-09-01'
Create a new pipeline revision
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.
POST /ml/v4/pipelines/{pipeline_id}/revisionsRequest
Path Parameters
Pipeline identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines/:pipeline_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a pipeline.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The details of the pipeline to be created.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Pipeline revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the pipeline revisions
Retrieve the pipeline revisions.
GET /ml/v4/pipelines/{pipeline_id}/revisionsRequest
Path Parameters
Pipeline identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/pipelines/:pipeline_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of pipelines.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of pipelines.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Pipeline revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Create a new remote training system
Create a new remote training system with the given payload. A remote training system represents a remote system used by Federated Learning. This definition is necessary to control who can register to a federated learning job.
POST /ml/v4/remote_training_systems
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the remote training system. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe list of allowed identities that are allowed to access the remote system.
The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]A remote organization.
The details of the remote administrator for the organization and identities.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
Response
The information for a remote training system.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a remote system used by Federated Learning.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Remote training system created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the remote training systems
Retrieve the remote training systems for the specified space or project.
GET /ml/v4/remote_training_systems
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
Response
A paginated list of remote training systems.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of remote training systems.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the remote training system
Retrieve the remote training system 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.
GET /ml/v4/remote_training_systems/{remote_training_system_id}Request
Path Parameters
Remote training system identifier.
Example:
3067fdf1-252f-424b-b52d-5cdd981cae3
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
Response
The information for a remote training system.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a remote system used by Federated Learning.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the remote training system
Update the remote training system with the provided patch data. The following fields can be patched:
/tags/name/description/custom/organization/allowed_identities/remote_admin
PATCH /ml/v4/remote_training_systems/{remote_training_system_id}Request
Path Parameters
Remote training system identifier.
Example:
3067fdf1-252f-424b-b52d-5cdd981cae3
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
Response
The information for a remote training system.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a remote system used by Federated Learning.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Remote training system has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the remote training system
Delete the remote training system with the specified identifier. This will delete all revisions of this remote training system as well. For each revision all attachments will also be deleted.
DELETE /ml/v4/remote_training_systems/{remote_training_system_id}Request
Path Parameters
Remote training system identifier.
Example:
3067fdf1-252f-424b-b52d-5cdd981cae3
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Create a new remote training system revision
Create a new remote training system revision.
The current metadata and content for
remote_training_system_id will be taken and a new revision created.
Either space_id or project_id has to be provided and is mandatory.
POST /ml/v4/remote_training_systems/{remote_training_system_id}/revisionsRequest
Path Parameters
Remote training system identifier.
Example:
3067fdf1-252f-424b-b52d-5cdd981cae3
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
Response
The information for a remote training system.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The definition of a remote system used by Federated Learning.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Remote training system revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the remote training system revisions
Retrieve the remote training system revisions.
GET /ml/v4/remote_training_systems/{remote_training_system_id}/revisionsRequest
Path Parameters
Remote training system identifier.
Example:
3067fdf1-252f-424b-b52d-5cdd981cae3
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
Response
A paginated list of remote training systems.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of remote training systems.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Remote training system revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The training_data_references contain the training datasets and the
results_reference the connection where results will be stored.
The training results.
- results_reference
The data source type like
connection_assetordata_asset.Allowable values: [
connection_asset,data_asset,container,url]Example:
connection_assetContains a set of fields that describe the location of the data with respect to the
connection.Examples:{ "bucket": "wml-v4-fvt-remote-tests", "file_name": "heart_testpy379.csv" }- location
Item identification inside a collection.
Contains a set of fields specific to each connection. See here for details about specifying connections.
Examples:{ "id": "2d07a6b4-8fa9-43ab-91c8-befcd9dab8d2" }
A reference to a resource.
A pipeline. The
hardware_specis a reference to the hardware specification. Thehybrid_pipeline_hardware_specsare used only when training a hybrid pipeline in order to specify compute requirement for each pipeline node.A model. The
software_specis a reference to a software specification. Thehardware_specis a reference to a hardware specification.Federated Learning.
Training datasets.
The holdout/test datasets.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]The name of the training.
Example:
my-trainingA description of the training.
Example:
My first training.The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987f
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/trainings?version=%3Cdate%3E' --data-raw '{ "experiment": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2" }, "pipeline": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "data_bindings": [ { "data_reference_name": "<string>", "node_id": "<string>" }, { "data_reference_name": "<string>", "node_id": "<string>" } ], "nodes_parameters": [ { "node_id": "<string>", "parameters": "<object>" }, { "node_id": "<string>", "parameters": "<object>" } ], "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "hybrid_pipeline_hardware_specs": [ { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } }, { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } } ] }, "model_definition": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "software_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "..." }, "command": "<string>", "parameters": "<object>" }, "training_data_references": [ { "type": "<string>", "id": "<string>", "connection": "<object>", "location": "<object>", "schema": { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } }, { "type": "<string>", "id": "<string>", "connection": "<object>", "location": "<object>", "schema": { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } } ], "results_reference": { "type": "<string>", "location": "<object>", "id": "<string>", "connection": "<object>" }, "tags": [ "t1", "t2" ], "name": "my-training", "description": "My first training.", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }'
Response
Training resource.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
The training job has been created.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the list of trainings
Retrieve the list of trainings for the specified space or project.
GET /ml/v4/trainings
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07Token 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
nextfield.How many resources should be returned. Default value is 100. Max value is 200.
Default:
100Compute the total count. May have performance impact.
Return only the resources with the given tag value.
Filter based on 'pipeline' or 'experiment' trainings. Example:
type=pipeline. If not provided, returns all the trainings.Filter based on on the training job state: queued, running, completed, failed etc.
The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcReturn the training jobs that are sub-jobs of this parent_id job. The parent_id can be the experiment job ID.
curl --request GET'https://us-south.ml.cloud.ibm.com/ml/v4/trainings?start=<string>&limit=100&total_count=<boolean>&tag.value=<string>&type=<string>&state=<string>&space_id=<string>&project_id=<string>&parent_id=<string>&version=<string>'
Response
Information for paging when querying resources.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
Training resource.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the training
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.
GET /ml/v4/trainings/{training_id}Request
Path Parameters
The training identifier.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/trainings?start=<string>&limit=100&total_count=<boolean>&tag.value=<string>&type=<string>&state=<string>&space_id=<string>&project_id=<string>&parent_id=<string>&version=2020-09-01'
Response
Training resource.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
In case of web socket upgrade, the service messages emitted have the following shape.
OK.
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Cancel the training
Cancel the specified training and remove it.
DELETE /ml/v4/trainings/{training_id}Request
Path Parameters
The training identifier.
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcSet to true in order to also delete the job metadata information.
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/trainings/:training_id?hard_delete=<boolean>&version=2020-09-01&space_id=<string>&project_id=<string>'
Create a new training definition
Create a new training definition with the given payload. A training definition represents the training meta-data necessary to start a training job.
POST /ml/v4/training_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
Payload for creating the training definition. Either space_id or project_id has to be provided and is mandatory.
The name of the resource.
Possible values: 1 ≤ length ≤ 250
Example:
my-resourceThe training results.
- results_reference
The data source type like
connection_assetordata_asset.Allowable values: [
connection_asset,data_asset,container,url]Example:
connection_assetContains a set of fields that describe the location of the data with respect to the
connection.Examples:{ "bucket": "wml-v4-fvt-remote-tests", "file_name": "heart_testpy379.csv" }- location
Item identification inside a collection.
Contains a set of fields specific to each connection. See here for details about specifying connections.
Examples:{ "id": "2d07a6b4-8fa9-43ab-91c8-befcd9dab8d2" }
The project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fThe space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fA description of the resource.
Possible values: length ≤ 1000
Example:
This is my first resource.A list of tags for this resource.
Possible values: number of items ≤ 64
Examples:[ "t1", "t2" ]A reference to a resource.
A pipeline. The
hardware_specis a reference to the hardware specification. Thehybrid_pipeline_hardware_specsare used only when training a hybrid pipeline in order to specify compute requirement for each pipeline node.A model. The
software_specis a reference to a software specification. Thehardware_specis a reference to a hardware specification.Federated Learning.
Training datasets.
The holdout/test datasets.
User defined properties specified as key-value pairs.
Examples:{ "name": "model", "size": 2 }- custom
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions?version=2020-09-01' --data-raw '{ "name": "my-resource", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "description": "This is my first resource.", "tags": [ "t1", "t2" ], "experiment": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2" }, "pipeline": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "data_bindings": [ { "data_reference_name": "<string>", "node_id": "<string>" }, { "data_reference_name": "<string>", "node_id": "<string>" } ], "nodes_parameters": [ { "node_id": "<string>", "parameters": "<object>" }, { "node_id": "<string>", "parameters": "<object>" } ], "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "hybrid_pipeline_hardware_specs": [ { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } }, { "node_runtime_id": "auto_ai.kb", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" } } ] }, "model_definition": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "model_type": "<string>", "hardware_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "<string>", "num_nodes": "<integer>" }, "software_spec": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab", "rev": "2", "name": "..." }, "command": "<string>", "parameters": "<object>" }, "training_data_references": [ { "type": "<string>", "id": "<string>", "connection": "<object>", "location": "<object>", "schema": { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } }, { "type": "<string>", "id": "<string>", "connection": "<object>", "location": "<object>", "schema": { "id": "<string>", "fields": [ { "name": "duration", "type": "number" } ], "name": "<string>" } } ], "results_reference": { "type": "<string>", "location": "<object>", "id": "<string>", "connection": "<object>" } }'
Response
The information for a training definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Training definition created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the training definitions
Retrieve the training definitions for the specified space or project.
GET /ml/v4/training_definitions
Request
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50Return only the resources with the given tag values, separated by
ororandto support multiple tags.Example:
tf2.0 or tf2.1Returns 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.
Possible values: length ≥ 1
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions?space_id=<string>&project_id=<string>&start=<string>&limit=100&tag.value=<string>&version=2020-09-01'
Response
A paginated list of training definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of training definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the training definition
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.
GET /ml/v4/training_definitions/{training_definition_id}Request
Path Parameters
Training definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcThe revision number of the resource.
Example:
2
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions/:training_definition_id?space_id=<string>&project_id=<string>&rev=<string>&version=2020-09-01'
Response
The information for a training definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
OK
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Update the training definition
Update the training definition with the provided patch data. The following fields can be patched:
/tags/name/description/custom/federated_learning
PATCH /ml/v4/training_definitions/{training_definition_id}Request
Path Parameters
Training definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).
The operation to be performed.
Allowable values: [
add,remove,replace]The pointer that identifies the field that is the target of the operation.
The value to be used within the operation.
curl --request PATCH 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions/:training_definition_id?space_id=<string>&project_id=<string>&version=2020-09-01' --data-raw '[ { "op": "<string>", "path": "<string>", "value": "<object>" }, { "op": "<string>", "path": "<string>", "value": "<object>" } ]'
Response
The information for a training definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Training definition has been patched successfully
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Delete the training definition
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.
DELETE /ml/v4/training_definitions/{training_definition_id}Request
Path Parameters
Training definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edc
curl --request DELETE 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions/:training_definition_id?space_id=<string>&project_id=<string>&version=2020-09-01'
Create a new training definition revision
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.
POST /ml/v4/training_definitions/{training_definition_id}/revisionsRequest
Path Parameters
Training definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07
The details for the revision.
{
"space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f",
"commit_message": "Updated for TF 2.0"
}The space that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
3fc54cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idhas to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
12ac4cf1-252f-424b-b52d-5cdd9814987fAn optional commit message for the revision.
curl --request POST 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions/:training_definition_id/revisions?version=2020-09-01' --data-raw '{ "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" }'
Response
The information for a training definition.
Common metadata for a resource where
project_idorspace_idmust be present.Examples:{ "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "rev": "2", "owner": "guy", "created_at": "2020-05-02T16:27:51Z", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" }, "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }The
training_data_referencescontain the training datasets and theresults_referencethe connection where results will be stored.Optional details coming from the service and related to the API call or the associated resource.
Status Code
Training definition revision created
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.
No Sample Response
Retrieve the training definition revisions
Retrieve the training definition revisions.
GET /ml/v4/training_definitions/{training_definition_id}/revisionsRequest
Path Parameters
Training definition identifier.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987f
Query Parameters
The version date for the API of the form
YYYY-MM-DD.Example:
2023-07-07The space that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fThe project that contains the resource. Either
space_idorproject_idquery parameter has to be given.Possible values: length = 36, Value must match regular expression
^[a-zA-Z0-9-]*$Example:
a77190a2-f52d-4f2a-be3d-7867b5f46edcToken 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
nextfield.How many resources should be returned. By default limit is 100. Max limit allowed is 200.
Possible values: 1 ≤ value ≤ 200
Default:
100Example:
50
curl --request GET 'https://us-south.ml.cloud.ibm.com/ml/v4/training_definitions/:training_definition_id/revisions?space_id=<string>&project_id=<string>&start=<string>&limit=100&version=2020-09-01'
Response
A paginated list of training definitions.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
The total number of resources. Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
Example:
1A reference to the first item of the next page, if any.
A list of training definitions.
Optional details coming from the service and related to the API call or the associated resource.
Status Code
Training definition revisions
Bad request, the response body should contain the reason.
Unauthorized.
Forbidden, an authentication error including trying to access an unauthorized space or project.
The specified resource was not found.