Introduction

IBM Watson OpenScale is an enterprise-grade environment for AI infused applications that provides enterprises with visibility into how AI is being built, used, and delivering ROI – at the scale of their business.

For details about using IBM Watson OpenScale, see the docs.

Authentication

You authenticate to the API by using IAM. You can pass either a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

IAM authentication. Replace {token} with the bearer token returned by the IAM authentication service.

curl -X GET --header "Authorization: Bearer {Token}" "https://api.aiopenscale.cloud.ibm.com/<SERVICE_INSTANCE_ID>/v2/data_marts"

Security scheme

Authentication to this API's methods uses one of the following security schemes.

IAM

Value
  • API Key
  • Authorization
  • Header

ICP4D

Value
  • API Key
  • Authorization
  • Header

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When we change the API in a backwards-incompatible way, we release a new version date.

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. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

This documentation describes the current version of IBM Watson OpenScale, 2021-02-10. In some cases, differences in earlier versions are noted in the descriptions of parameters and response models.

Error handling

The IBM Watson OpenScale service uses standard HTTP response codes to indicate indicate if a method completed successfully.A 200 HTTP response always indicates success. HTTP response codes with the format 4xx indicate a failure. A 500 HTTP response code usually indicates an internal system error that cannot be resolved by the user.

ErrorResponse

Name Description
code
integer
HTTP error code.
error
string
Human-readable error string, like 'Invalid image file'.

ErrorAuthentication

Name Description
status
string
The status of error.
statusInfo
string
Information about the error.

ErrorHTML

Name Description
Error
string
HTML description of the error.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code
integer
HTTP error code.
description
string
Human-readable error description. For example, File size limit exceeded.
error_id
string
Codified error string. For example, limit_exceeded.

Methods

List all data sets specified by the parameters

GET /v2/data_sets

Request

Query Parameters

  • ID of the data set target (e.g. subscription ID, business application ID)

  • type of the target

    Allowable values: [subscription,business_application,instance,data_mart]

  • type of the data set

    Allowable values: [manual_labeling,payload_logging,feedback,business_payload,explanations,explanations_whatif,training,custom]

  • ID of the managing entity (e.g. business application ID)

  • curl -X GET   https://aiopenscale.cloud.ibm.com/openscale/<INSTANCE_ID>/v2/data_sets?target.target_id=<SUBSCRIPTION_ID>&target.target_type=subscription&type=payload_logging   -H 'Accept: application/json'

Response

Status Code

  • response

Example responses
  • {
      "data_sets": [
        {
          "metadata": {
            "id": "string",
            "crn": "crn:v1:bluemix:public:aiopenscale:us-south:a/{account-id}:{instance-id}:{resource-type}:{resource-id}",
            "url": "string",
            "created_at": "2021-02-12T11:29:15.530Z",
            "created_by": "IBMid-1100011XYZ",
            "modified_at": "2021-02-12T11:29:15.530Z",
            "modified_by": "IBMid-1100011XYZ"
          },
          "entity": {
            "data_mart_id": "dad3ed3f-db8d-4b35-b59e-7acad5348a3a",
            "name": "string",
            "description": "string",
            "type": "payload_logging",
            "target": {
              "target_type": "subscription",
              "target_id": "4b133ea1-3097-4175-82a1-4fd80759de26"
            },
            "schema_update_mode": "none",
            "data_schema": {
              "type": "struct",
              "fields": [
                {
                  "name": "string",
                  "type": "string",
                  "nullable": true
                }
              ],
              "id": "string",
              "name": "string"
            },
            "location": {
              "table_name": "string"
            },
            "managed_by": "string",
            "status": {
              "state": "active",
              "deleted_at": "string",
              "failure": {
                "trace": "string",
                "errors": [
                  {
                    "code": "AISUT0002E",
                    "message": "string",
                    "parameters": [
                      "string"
                    ]
                  }
                ]
              }
            }
          }
        }
      ]
    }

Add scoring payload / feedback payload

Add scoring payload or feedback payload as dataset records. Use payload logging dataset id (dataset of type 'payload_logging') when storing payload records and use feedback dataset id (dataset of type 'feedback') when storing feedback payload

POST /v2/data_sets/{data_set_id}/records

Request

Custom Headers

  • Allowable values: [application/json,text/csv,multipart/form-data]

Path Parameters

  • ID of the data set

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+

    Example: 59e92703-febe-4eda-abfa-09261c48f3dd

Query Parameters

  • if not provided service will attempt to automatically detect header in the first line

  • skip number of rows from input

  • limit for number of processed input rows

  • delimiter character for data provided as csv

  • expected behaviour on error

    Allowable values: [stop,continue]

  • maximum length of single line in bytes (default 10MB)

Examples:
Dict
List
Scoring
  • curl -X POST   https://aiopenscale.cloud.ibm.com/openscale/<INSTANCE_ID>/v2/data_sets/<PAYLOAD_DATASET_ID>/records     -H 'Authorization: Bearer <IAM_token>'     -H 'Content-Type: application/json'     -d '[{}]'

Response

Status Code

  • response

Example responses
  • {
      "state": "preparing",
      "deleted_at": "string",
      "failure": {
        "trace": "string",
        "errors": [
          {
            "code": "AISUT0002E",
            "message": "string",
            "parameters": [
              "string"
            ]
          }
        ]
      }
    }

List data set records

List data set records (Feedback or Payload records)

GET /v2/data_sets/{data_set_id}/records

Request

Path Parameters

  • ID of the data set

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+

    Example: 59e92703-febe-4eda-abfa-09261c48f3dd

Query Parameters

  • return records with timestamp grather then or equal to start parameter

    Example: 2018-01-01T00:00:00Z

  • return records with timestamp lower then end parameter

    Example: 2018-01-31T00:00:00Z

  • limit for number of returned records. If the value is greater than 1000 than it will be truncated.

    Default: 100

  • offset of returned records

  • return record annotations with given names

    Examples:
    View
  • Only return records that match given filters. There are two types of filters, separated by commas:

    • normal filter (multiple are possible), {field_name}:{op}:{value} — filter records directly
    • joining filter (only a single one is possible), {data_set_id}.{field_name}:{op}:{value} — join a data set by transaction_id (the user must ensure it's provided!) and filter by this data set's records' field. Will fail if the user hasn't provided transaction_id for both data sets' records. Filters of different types can be mixed. They are partly compatible with the ones in POST /v2/data_sets/{data_set_id}/distributions.

    Available operators: | op | meaning | example | code equivalent | |:----:|:---------------------------:|:------------------:|:------------------------:| | eq | equality | field:eq:value | field == value | | gt | greater than | field:gt:value | field > value | | gte | greater or equal | field:gte:value | field >= value | | lt | less than | field:lt:value | field < value | | lte | less or equal | field:lte:value | field <= value | | like | matching a simple pattern* | field:like:pattern | pattern.match(field) | | in | is contained in list | field:in:a;b;c | [a,b,c].contains(field) |

      • "%" means "one or more character", "_" means "any single character", other characters have their usual, literal meaning (e.g. "|" means character "|")
    Examples:
    normal_filters
    joined_filter
    mixed_filters
  • If total_count should be included. It can have performance impact if total_count is calculated.

  • What JSON format to use on output.

    Allowable values: [dict,list]

    Default: dict

  • Binary data presentation format. By default, the binary field value is encoded to base64 string. If reference is chosen, every binary field is moved to the references section with value set to an uri to the particular field within the record that can be GET in a separate request.

    Allowable values: [reference]

  • curl -X GET   https://aiopenscale.cloud.ibm.com/openscale/<INSTANCE_ID>/v2/data_sets/<DATASET_ID>/records?start=2021-02-12T00:00:00Z&end=2021-02-13T00:00:00Z&limit=100&format=dict   -H 'Accept: application/json'   -H 'Authorization: Bearer <TOKEN>'

Response

dict format

Status Code

  • response

Example responses
  • {
      "total_count": 2,
      "records": [
        {
          "metadata": {
            "id": "string",
            "crn": "crn:v1:bluemix:public:aiopenscale:us-south:a/{account-id}:{instance-id}:{resource-type}:{resource-id}",
            "url": "string",
            "created_at": "2019-10-31T15:18:20.629Z",
            "created_by": "IBMid-1100011XYZ",
            "modified_at": "2019-10-31T15:18:20.629Z",
            "modified_by": "IBMid-1100011XYZ"
          },
          "entity": {
            "values": {
              "GENDER": "M",
              "PRODUCT_LINE": "Golf Equipment",
              "AGE": 25,
              "MARITAL_STATUS": "Unspecified",
              "PROFESSION": "Sales"
            },
            "annotations": {
              "biased": {
                "fairness_score": 0.62
              }
            }
          }
        },
        {
          "metadata": {
            "id": "string",
            "crn": "crn:v1:bluemix:public:aiopenscale:us-south:a/{account-id}:{instance-id}:{resource-type}:{resource-id}",
            "url": "string",
            "created_at": "2019-10-31T15:18:20.630Z",
            "created_by": "IBMid-1100011XYZ",
            "modified_at": "2019-10-31T15:18:20.630Z",
            "modified_by": "IBMid-1100011XYZ"
          },
          "entity": {
            "values": {
              "GENDER": "M",
              "PRODUCT_LINE": "Sport shoes",
              "AGE": 28,
              "MARITAL_STATUS": "Married",
              "PROFESSION": "Sales"
            },
            "annotations": {
              "biased": {
                "fairness_score": 0.72
              }
            }
          }
        }
      ]
    }
  • {
      "total_count": 2,
      "records": [
        {
          "fields": [
            "GENDER",
            "PRODUCT_LINE",
            "AGE",
            "MARITAL_STATUS",
            "PROFESSION"
          ],
          "values": [
            [
              "M",
              "Golf Equipment",
              25,
              "Unspecified",
              "Sales"
            ],
            [
              "M",
              "Sport shoes",
              28,
              "Married",
              "Sales"
            ]
          ],
          "annotations": [
            {
              "biased": {
                "fairness_score": 0.62
              }
            },
            {
              "biased": {
                "fairness_score": 0.72
              }
            }
          ]
        }
      ]
    }

Compute explanations

Submit tasks for computing explanation of predictions

POST /v2/explanation_tasks

Request

Explanation task request to submit for computing explanation. One of scoring_ids and input_rows is mandatory.

  • curl -X POST   https://aiopenscale.cloud.ibm.com/openscale/<INSTANCE_ID>/v2/explanation_tasks   -H 'Accept: application/json'   -H 'Content-Type: application/json'   -H 'Authorization: Bearer <TOKEN>'   -d '{
        "scoring_ids": [
          "scoring_id1"
        ],
        "explanation_types": [
          "lime"
        ],
        "subscription_id": "c37c3c7c-67ae-48be-84bd-86cd2b25e618"
      }'

Response

Post explanation tasks response

Status Code

  • Explanation request submitted successfully

Example responses
  • {
      "metaddata": {
        "explanation_task_ids": [
          "explanation_task_ids"
        ],
        "created_by": "IBMid-123456",
        "created_at": "2018-11-01T09:16:45.783Z"
      }
    }

Get explanation

Get explanation for the given explanation task id

GET /v2/explanation_tasks/{explanation_task_id}

Request

Path Parameters

  • ID of the explanation task

    Example: 9fdaa46c-c124-4700-b794-6d6a5262c3aa

Query Parameters

  • Unique subscription ID

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+

    Example: c37c3c7c-67ae-48be-84bd-86cd2b25e618

  • curl -X GET   https://aiopenscale.cloud.ibm.com/openscale/<INSTANCE_ID>/v2/explanation_tasks/scoring_id1?subscription_id=<SUBSCRIPTION_ID>   -H 'Accept: application/json'   -H 'Authorization: Bearer <TOKEN>'

Response

Get explanation task response

Status Code

  • Explanation successfully retrieved

Example responses
  • {
      "metaddata": {
        "explanation_task_id": "my_task_id",
        "created_at": "2021-02-12T11:29:15.530Z",
        "created_by": "IBMid-1100011XYZ",
        "modified_at": "2021-02-12T11:29:15.530Z",
        "modified_by": "IBMid-1100011XYZ"
      },
      "entity": {
        "status": {
          "state": "active"
        },
        "asset": {
          "id": "asset_id",
          "name": "asset_name",
          "input_data_type": "structured",
          "problem_type": "binary",
          "deployment": {
            "id": "deployment_id",
            "name": "deployment_name"
          }
        },
        "input_features": [
          {
            "name": "feature_name",
            "value": "feature_value",
            "feature_type": "numerical"
          }
        ],
        "perturbed": false,
        "explanations": [
          {
            "explanation_type": "lime",
            "predictions": [
              {
                "value": "class1",
                "probability": 0.8,
                "explanation_features": [
                  {
                    "feature_name": "feature_name",
                    "weight": 0.18,
                    "importance": 1,
                    "feature_value": "feature_value",
                    "feature_range": {
                      "min": 10,
                      "min_inclusive": true,
                      "max": 100,
                      "max_inclusive": false
                    }
                  }
                ]
              }
            ]
          },
          {
            "explanation_type": "contrastive",
            "pertinent_positive": {
              "features": [
                {
                  "feature_name": "feature_name",
                  "weight": 0.18,
                  "importance": 1,
                  "feature_value": "feature_value",
                  "feature_range": {
                    "min": 10,
                    "min_inclusive": true,
                    "max": 100,
                    "max_inclusive": false
                  }
                }
              ]
            },
            "pertinent_negative": {
              "features": [
                {
                  "feature_name": "feature_name",
                  "weight": 0.18,
                  "importance": 1,
                  "feature_value": "feature_value",
                  "feature_range": {
                    "min": 10,
                    "min_inclusive": true,
                    "max": 100,
                    "max_inclusive": false
                  }
                }
              ],
              "prediction": "class2",
              "probability": 0.6
            }
          }
        ]
      }
    }

Computes the bias mitigation/remediation for the specified model

Computes the bias mitigation/remediation for the specified model. The fairness monitoring debias request payload details must be valid.

POST /v2/subscriptions/{subscription_id}/predictions

Request

Path Parameters

  • Unique subscription ID

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+

    Example: c37c3c7c-67ae-48be-84bd-86cd2b25e618

  • curl -k -X POST   https://<ICP_HOSTNAME>:<PORT>/openscale/<INSTANCE_ID>/v2/subscriptions/<SUBSCRIPTION_ID>/predictions   -H 'Accept: application/json'   -H 'Authorization: Bearer <TOKEN>'   -H 'X-Global-Transaction-Id: xxxxxxx'   -H 'Content-Type: application/json'   -d '{
        "fields":
          [
            "field1",
            "field2",
            "field3"
          ],
        "values":
          [
            [
              "field1Value1",
              "field2Value1",
              "field3Value1"
            ],
            [
              "field1Value2",
              "field2Value2",
              "field3Value2"
            ]
          ]
        }'

Response

Status Code

  • Accepted

Example responses
  • {
      "fields": [
        "name",
        "age",
        "position",
        "prediction",
        "probability",
        "debiased_prediction",
        "debiased_probability",
        "debiased_decoded_target"
      ],
      "values": [
        [
          "john",
          35,
          "engineer",
          0.3,
          [
            0.754601226993865,
            0.24539877300613497
          ],
          0.4,
          [
            0.754601226993865,
            0.24539877300613497
          ],
          "good"
        ]
      ]
    }