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/v1/data_marts/{data_mart_id}/deployment_metrics?version=2018-09-17"

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, 2018-09-17. 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.

Data labels

You can remove customer data if you associate the customer and the data when you send the information to a service. First you label the data with a customer ID, and then you can delete the data by the ID. Labeling data is used only by methods that accept customer data. For more information about {{site.data.keyword.aiopenscaleshort}} and labeling data, see Information security.

  • Use the X-Watson-Metadata header to associate a customer ID with the data. By adding a customer ID to a request, you indicate that it contains data that belongs to that customer.

    Specify a random or generic string for the customer ID. Do not include personal data, such as an email address. Pass the string customer_id={id} as the argument of the header.

  • Use the Delete labeled data method to remove data that is associated with a customer ID.

Data collection

By default, all IBM services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public.

To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out request header to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access for general service improvements.

Example request

curl -u "apikey:{apikey}" -H "X-Watson-Learning-Opt-Out: true" "https://gateway.watsonplatform.net/ai-openscale/api/v1/{method}"

Methods

Publish Scoring Payload

Publish scoring payload for a given deployment to OpenScale DataMart. It will be stored in database asynchronously.

POST /v1/data_marts/{data_mart_id}/scoring_payloads
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Response

Status Code

  • Accepted

Example responses

Post Feedback Payload

Upload feedback payload.

POST /v1/data_marts/{data_mart_id}/feedback_payloads
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Example:
Response

Status Code

  • Feedback registered

No Sample Response

This method does not specify any sample responses.

Get Feedback

Get feedback data.

GET /v1/data_marts/{data_mart_id}/service_bindings/{binding_id}/subscriptions/{subscription_id}/feedback_payloads
Request

Custom Headers

  • Allowable values: [application/json,text/csv]

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Query Parameters

  • if true header will be first line of the csv content

    Default: false

  • delimiter character for csv data

    Default: ,

Response

Status Code

  • response

Example responses

Log Feedback

Send feedback data to the service.

POST /v1/data_marts/{data_mart_id}/service_bindings/{binding_id}/subscriptions/{subscription_id}/feedback_payloads
Request

Custom Headers

  • Allowable values: [application/json,text/csv]

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Query Parameters

  • if true header will be first line of the csv content

    Default: false

  • delimiter character for csv data

    Default: ,

  • expected behaviour on error

    Allowable values: [stop,continue]

    Default: stop

  • skip number of rows from input

  • limit for number of processed input rows

Response

Status Code

  • response

No Sample Response

This method does not specify any sample responses.

Post Explanation Task

Submit task for computing explanation of a prediction

POST /v1/data_marts/{data_mart_id}/explanation_tasks
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Response

Status Code

  • Explanation request submitted successfully

No Sample Response

This method does not specify any sample responses.

Get Explanation Task

Get explanation for the given explanation task id

GET /v1/data_marts/{data_mart_id}/explanation_tasks/{explanation_task_id}
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

  • ID of the explanation task

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

Response

Status Code

  • Explanation successfully retrieved

No Sample Response

This method does not specify any sample responses.

Post fairness monitoring

Computes the bias mitigation/remediation for the specified model. The fairness monitoring debias request payload details must be valid. Makes an online prediction and de-bias prediction on a given data values.

The de-bias request payload takes a batch of input rows which should have model fields and values, in the following format.

{
    "fields": [
        "name",
        "age",
        "position"
    ],
    "values": [
        [
        "john",
        33,
        "engineer"
        ],
        [
        "mike",
        23,
        "student"
        ]
    ]
}

The response of this API would contain regular prediction columns provided by the underlying machine learning model engine, and along with that would contain de-biased predictions as listed in the following format.

{
    "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.898098798985,
                0.49877
            ],
            "good"
        ],
        [
            "mike",
            23,
            "student",
            0.5,
            [
                0.2794765664946941,
                0.7205234335053059
            ],
            0.6,
            [
                0.407098,
                0.86756785758667
            ],
            "bad"
        ]
    ]
}
POST /v1/data_marts/{data_mart_id}/service_bindings/{binding_id}/subscriptions/{subscription_id}/deployments/{deployment_id}/online
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

  • The transaction ID/scoring ID to the given payload.

Path Parameters

  • AIOS OpenScale DataMart ID - the service instance ID.

  • The Model engine binding ID.

  • The subscription ID.

  • The deployment ID.

Response

Status Code

  • Accepted

  • You are not authorized to perform this action.

  • You are not permitted to perform this action.

  • An service error occurred. The fairness monitoring debias was not initiated.

Example responses

Export subscription

Export the subscription configuration.

GET /v1/data_marts/{data_mart_id}/service_bindings/{binding_id}/subscriptions/{subscription_id}/file
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Response

Status Code

  • response

Example responses

Import subscription

Import a subscription configuration.

PUT /v1/data_marts/{data_mart_id}/service_bindings/{binding_id}/subscriptions/{subscription_id}/file
Request

Path Parameters

  • OpenScale DataMart ID - the service instance ID

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

Query Parameters

  • expected behaviour on error

    Allowable values: [stop,continue]

    Default: stop

Example:
Response

Status Code

  • response

No Sample Response

This method does not specify any sample responses.