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"
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. |
errorstring |
Human-readable error string, like 'Invalid image file'. |
ErrorAuthentication
Name | Description |
---|---|
statusstring |
The status of error. |
statusInfostring |
Information about the error. |
ErrorHTML
Name | Description |
---|---|
Errorstring |
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. |
descriptionstring |
Human-readable error description. For example, File size limit exceeded . |
error_idstring |
Codified error string. For example, limit_exceeded . |
Methods
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
{ "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)
Fields and values of the entity matches JSON object's fields and values.
No properties to display
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 '[{}]'
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
parameterExample:
2018-01-01T00:00:00Z
return records with timestamp lower then
end
parameterExample:
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:ViewOnly 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_filtersjoined_filtermixed_filtersIf 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
Number of all rows which satisfy the query. It is calculated and returned when include_total_count query param is set to
true
Status Code
response
{ "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.
Unique subscription ID.
Example:
c37c3c7c-67ae-48be-84bd-86cd2b25e618
IDs of the scoring transaction
Examples:ViewList of scoring transactions
Examples:Viewinput_rows
Types of explanations to generate
Allowable values: [
lime
,contrastive
]
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" }'
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
Metadata of get explanation task response
Entity of get explanation task response
Status Code
Explanation successfully retrieved
{ "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
The values associated to the fields
Examples:ViewThe fields to process debias scoring
Examples:View
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
The fields of the model processed debias scoring.
Examples:ViewThe values associated to the fields.
Examples:View
Status Code
Accepted
{ "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" ] ] }