Watson OpenScale v2 API - IBM Cloud API Docs

Introduction

Last updated: 2021-02-10

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

Attribute

Value

Type
API Key
Name
Authorization
In
Header

ICP4D

Attribute

Value

Type
API Key
Name
Authorization
In
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`.

GET /v2/data_sets

Request

Query Parameters

target.target_id
string
ID of the data set target (e.g. subscription ID, business application ID)
target.target_type
string
type of the target

Allowable values: [subscription,business_application,instance,data_mart]
type
string
type of the data set

Allowable values: [manual_labeling,payload_logging,feedback,business_payload,explanations,explanations_whatif,training,custom]
managed_by
string
ID of the managing entity (e.g. business application ID)

Example request

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

Response Body

DataSetResponseCollection

Status Code

200
response

Example responses

Status 200

{
  "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 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

Content-Type
string
Allowable values: [application/json,text/csv,multipart/form-data]

Path Parameters

data_set_id
Required*
string
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

header
boolean
if not provided service will attempt to automatically detect header in the first line
skip
integer
skip number of rows from input
limit
integer
limit for number of processed input rows
delimiter
string
delimiter character for data provided as csv
on_error
string
expected behaviour on error

Allowable values: [stop,continue]
csv_max_line_length
number
maximum length of single line in bytes (default 10MB)

Request Body

Required*

[]

Examples:

Dict

List

Scoring

Example request

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

Response Body

Status

Status Code

202
response

Example responses

Status 202

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

List data set records (Feedback or Payload records)

GET /v2/data_sets/{data_set_id}/records

Request

Path Parameters

data_set_id
Required*
string
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

start
date-time
return records with timestamp grather then or equal to start parameter

Example: 2018-01-01T00:00:00Z
end
date-time
return records with timestamp lower then end parameter

Example: 2018-01-31T00:00:00Z
limit
integer
limit for number of returned records. If the value is greater than 1000 than it will be truncated.

Default: 100
offset
integer
offset of returned records
annotations
string[]
return record annotations with given names

Examples:
View
filter
string
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
include_total_count
boolean
If total_count should be included. It can have performance impact if total_count is calculated.
format
string
What JSON format to use on output.

Allowable values: [dict,list]
Default: dict
binary_format
string
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]

Example request

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

Response Body

One of

dict format

Status Code

200
response

Example responses

Status 200: dict format

{
  "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
          }
        }
      }
    }
  ]
}

Status 200: list format

{
  "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
          }
        }
      ]
    }
  ]
}

Submit tasks for computing explanation of predictions

POST /v2/explanation_tasks

Request

Request Body

Required*

ExplanationTaskRequest

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

Example request

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

Response Body

PostExplanationTaskResponse

Post explanation tasks response

Status Code

202
Explanation request submitted successfully

Example responses

Status 202

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

Get explanation for the given explanation task id

GET /v2/explanation_tasks/{explanation_task_id}

Request

Path Parameters

explanation_task_id
Required*
string
ID of the explanation task

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

Query Parameters

subscription_id
string
Unique subscription ID

Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+
Example: c37c3c7c-67ae-48be-84bd-86cd2b25e618

Example request

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

Response Body

GetExplanationTaskResponse

Get explanation task response

Status Code

200
Explanation successfully retrieved

Example responses

Status 200

{
  "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. The fairness monitoring debias request payload details must be valid.

POST /v2/subscriptions/{subscription_id}/predictions

Request

Path Parameters

subscription_id
Required*
string
Unique subscription ID

Possible values: 1 ≤ length ≤ 64, Value must match regular expression [a-z0-9_\-]+
Example: c37c3c7c-67ae-48be-84bd-86cd2b25e618

Request Body

Required*

FairnessMonitoringRemediationRequest

Example request

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

Response Body

FairnessMonitoringRemediation

Status Code

200
Accepted

Example responses

Status 200

{
  "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"
    ]
  ]
}

Introduction

Authentication

Security scheme

IAM

Attribute

Type

Name

In

ICP4D

Attribute

Type

Name

In

Versioning

Error handling

Related information

Methods

List all data sets specified by the parameters

Request

Query Parameters

target.target_id

target.target_type

type

managed_by

Response

Response Body

data_sets

Status Code

200

Add scoring payload / feedback payload

Request

Custom Headers

Content-Type

Path Parameters

data_set_id

Query Parameters

header

skip

limit

delimiter

on_error

csv_max_line_length

Request Body

Response

Response Body

state

deleted_at

failure

Status Code

202

List data set records

Request

Path Parameters

data_set_id

Query Parameters

start

end

limit

offset

annotations

filter

include_total_count

format

binary_format

Response

Response Body

records

total_count

Status Code

200

Compute explanations

Request

Request Body

scoring_ids

input_rows

any property

explanation_types

subscription_id

Response

Response Body