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 Deploying AIhttps://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-overview.html?context=analytics. There is a specialized python libraryhttps://ibm.github.io/watsonx-ai-python-sdk/ that is available to access this REST API. Endpoint URLs <-- Regional public endpoints -- 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 Toronto - https://ca-tor.ml.cloud.ibm.com Mumbai - https://ap-south-1.aws.wxai.ibm.com Example request to a Dallas endpoint: sh curl -H "Authorization: Bearer {token}" -X {requestmethod} "https://us-south.ml.cloud.ibm.com/{methodendpoint}" Replace {requestmethod}, and {methodendpoint} 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 tokenhttps://cloud.ibm.com/docs/account?topic=account-iamtokenfromapikeyiamtokenfromapikey in API requests. IAM authentication. Replace {token} and {url}/{method} with your service credentials. bash 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: bash 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 tokenshttps://cloud.ibm.com/docs/account?topic=account-iamtokenfromapikeyiamtokenfromapikey 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. | Error response | Name | Description | |--------|-------------------------------------------------------------------------------------------------------| | trace | An identifier that can be used to trace the request. This can be set using X-Global-Transaction-Id. | | errors | The list of errors. | Errors | Name | Description | |-----------|-------------------------------------------------------------------------| | code | A simple string code that should convey the general sense of the error. | | message | The message that describes the error. | | moreinfo | A reference to a more detailed explanation when available. | 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 Handbookhttps://cloud.ibm.com/docs/api-handbook?topic=api-handbook-changes-overviewdate-based-api-versioning for more details about date based API versioning. When there is a change to the API in a backwards-incompatible wayhttps://github.com/watson-developer-cloud/api-guidelines/versioning, 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. Deployed Version Dates 2021-05-01 The creation of deployment jobsdeployment-jobs-create is now fully asynchronous. What this means is that the creation of the job will not return the platformjobs section in the response, instead poll the job using the deployment-jobs-getdeployment-jobs-get operation until the platformjobs 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 connectionasset or dataasset 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 dataasset, requires an href to be supplied to the location object whereas using a connectionasset requires the connectionid for the connection object and different location fields depending on the data source type, see Data reference Descriptionhttps://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-data-sources.html?context=cpdaas&audience=wdp for details. <-- See here for a reference API for connectionshttps://api.dataplatform.cloud.ibm.com/v2/dataflows/doc/dataassetandconnectionproperties.html. -- Example dataasset payload: json { "trainingdatareferences": { "type": "dataasset", "location": { "href": "/v2/assets/Method Path Summary POST /ml/v4/deployments Create a new WML deployment GET /ml/v4/deployments Retrieve the deployments GET /ml/v4/deployments/{deployment_id} Retrieve the deployment details DELETE /ml/v4/deployments/{deployment_id} Delete the deployment PATCH /ml/v4/deployments/{deployment_id} Update the deployment metadata POST /ml/v4/deployments/{deployment_id}/predictions Execute a synchronous deployment prediction GET /ml/v4/deployment_jobs Retrieve the deployment jobs POST /ml/v4/deployment_jobs Start an asynchronous deployment job DELETE /ml/v4/deployment_jobs/{job_id} Cancel the deployment job GET /ml/v4/deployment_jobs/{job_id} Retrieve the deployment job POST /ml/v4/deployment_job_definitions Create a new deployment job definition GET /ml/v4/deployment_job_definitions Retrieve the deployment job definitions GET /ml/v4/deployment_job_definitions/{job_definition_id} Retrieve the deployment job definition PATCH /ml/v4/deployment_job_definitions/{job_definition_id} Update the deployment job definition DELETE /ml/v4/deployment_job_definitions/{job_definition_id} Delete the deployment job definition POST /ml/v4/deployment_job_definitions/{job_definition_id}/revisions Create a new deployment job definition revision GET /ml/v4/deployment_job_definitions/{job_definition_id}/revisions Retrieve the deployment job definition revisions POST /ml/v4/experiments Create a new experiment GET /ml/v4/experiments Retrieve the experiments GET /ml/v4/experiments/{experiment_id} Retrieve the experiment PATCH /ml/v4/experiments/{experiment_id} Update the experiment DELETE /ml/v4/experiments/{experiment_id} Delete the experiment POST /ml/v4/experiments/{experiment_id}/revisions Create a new experiment revision GET /ml/v4/experiments/{experiment_id}/revisions Retrieve the experiment revisions POST /ml/v4/functions Create a new function GET /ml/v4/functions Retrieve the functions GET /ml/v4/functions/{function_id} Retrieve the function PATCH /ml/v4/functions/{function_id} Update the function DELETE /ml/v4/functions/{function_id} Delete the function POST /ml/v4/functions/{function_id}/revisions Create a new function revision GET /ml/v4/functions/{function_id}/revisions Retrieve the function revisions PUT /ml/v4/functions/{function_id}/code Upload the function code GET /ml/v4/functions/{function_id}/code Download the function code GET /ml/v4/instances Retrieve the service instances GET /ml/v4/instances/{instance_id} Retrieve the service instance POST /ml/v4/models Create a new model GET /ml/v4/models Retrieve the models GET /ml/v4/models/{model_id} Retrieve the model PATCH /ml/v4/models/{model_id} Update the model DELETE /ml/v4/models/{model_id} Delete the model POST /ml/v4/models/{model_id}/revisions Create a new model revision GET /ml/v4/models/{model_id}/revisions Retrieve the model revisions GET /ml/v4/models/{model_id}/content Retrieve the model content metadata list PUT /ml/v4/models/{model_id}/content Upload the model content GET /ml/v4/models/{model_id}/content/{attachment_id} Download the model content DELETE /ml/v4/models/{model_id}/content/{attachment_id} Delete the model content GET /ml/v4/models/{model_id}/download Download the model content that matches a certain criteria POST /ml/v4/model_definitions Create a new model definition GET /ml/v4/model_definitions Retrieve the model definitions GET /ml/v4/model_definitions/{model_definition_id} Retrieve the model definition PATCH /ml/v4/model_definitions/{model_definition_id} Update the model definition DELETE /ml/v4/model_definitions/{model_definition_id} Delete the model definition POST /ml/v4/model_definitions/{model_definition_id}/revisions Create a new model definition revision GET /ml/v4/model_definitions/{model_definition_id}/revisions Retrieve the model definition revisions PUT /ml/v4/model_definitions/{model_definition_id}/model Upload the model definition model GET /ml/v4/model_definitions/{model_definition_id}/model Download the model definition model POST /ml/v4/pipelines Create a new pipeline GET /ml/v4/pipelines Retrieve the pipelines GET /ml/v4/pipelines/{pipeline_id} Retrieve the pipeline PATCH /ml/v4/pipelines/{pipeline_id} Update the pipeline DELETE /ml/v4/pipelines/{pipeline_id} Delete the pipeline POST /ml/v4/pipelines/{pipeline_id}/revisions Create a new pipeline revision GET /ml/v4/pipelines/{pipeline_id}/revisions Retrieve the pipeline revisions POST /ml/v4/trainings Create a new WML training GET /ml/v4/trainings Retrieve the list of trainings GET /ml/v4/trainings/{training_id} Retrieve the training DELETE /ml/v4/trainings/{training_id} Cancel the training POST /ml/v4/training_definitions Create a new training definition GET /ml/v4/training_definitions Retrieve the training definitions GET /ml/v4/training_definitions/{training_definition_id} Retrieve the training definition PATCH /ml/v4/training_definitions/{training_definition_id} Update the training definition DELETE /ml/v4/training_definitions/{training_definition_id} Delete the training definition POST /ml/v4/training_definitions/{training_definition_id}/revisions Create a new training definition revision GET /ml/v4/training_definitions/{training_definition_id}/revisions Retrieve the training definition revisions