Introduction

IBM Knowledge Catalog provides the capabilities for you to track data science models across the organization. View at a glance which models are in production and which need development or validation. Use the governance features to establish best practices to manage the communication flow from data scientists to ModelOps administrators.

Endpoint URLs

The Factsheet API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.dataplatform.cloud.ibm.com

Authentication

Before you can call a Watson Data API you must first create an IAM bearer token. Each token is valid only for one hour, and after a token expires you must create a new one if you want to continue using the API. The recommended method to retrieve a token programmatically is to create an API key for your IBM Cloud identity and then use the IAM token API to exchange that key for a token.

You can create a token in IBM Cloud or by using the IBM Cloud command line interface (CLI).

To create a token in the IBM Cloud:

Log in to IBM Cloud and select Manage > Security > Platform API Keys.
Create an API key for your own personal identity, copy the key value, and save it in a secure place. After you leave the page, you will no longer be able to access this value.
With your API key, set up Postman or another REST API tool and run the following command to the right

Curl command with API key to retrieve token

        curl "https://iam.cloud.ibm.com/identity/token" \
        -d "apikey=YOUR_API_KEY_HERE&grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -H "Authorization: Basic Yng6Yng="

Response

        {
        "access_token": "eyJraWQiOiIyMDE3MDgwOS0wMDowMDowMCIsImFsZyI6...",
        "refresh_token": "zmRTQFKhASUdF76Av6IUzi9dtB7ip8F2XV5fNgoRQ0mbQgD5XCeWkQhjlJ1dZi8K...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "expiration": 1505865282
        }

Use the value of the access_token property for your Factsheet API calls. Set the access_token value as the authorization header parameter for requests to the Watson Data APIs. The format is Authorization: Bearer <access_token_value_here>. For example: Authorization: Bearer eyJraWQiOiIyMDE3MDgwOS0wMDowMDowMCIsImFsZyI6IlJTMjU2In0...

To create a token by using the IBM Cloud CLI:

Follow the steps to install the CLI, log in to IBM Cloud, and get the token described here.

Remove Bearer from the returned IAM token value in your API calls.

Versioning

Factsheet API has a major, minor, and patch version, following industry conventions on semantic versioning: Using the version number format MAJOR.MINOR.PATCH, the MAJOR version is incremented when incompatible API changes are made, the MINOR version is incremented when functionality is added in a backwards-compatible manner, and the PATCH version is incremented when backwards-compatible bug fixes are made. The service major version is represented in the URL path.

Error Handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

| HTTP Error 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. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized to access '{namespace}'. | | 404 | Not Found | The requested resource could not be found. | | 500 | Internal Server Error | Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |

Model Inventory

A model inventory tracks Watson Machine Learning and external models that you add to model entries. This allows you to control which models to track for an organization without all of the overhead of tracking samples and other models that are not significant to the organization.

The model inventory is a repository in IBM Knowledge Catalog where you can request a new model, then track it through its lifecycle. A typical flow might go as follows:

A business user identifies a need for a machine learning model and creates a model entry to request a new model. The business owner assigns a potential name and states the basic parameters for the requested model.
When the request is saved, a model entry is created in the inventory and the tracking begins. Initially, the entry will be in the Awaiting development state as there are no assets to accompany the request.
When a data scientist creates a model for this business case, the data scientist chooses to track the model from the model details page of the project or deployment space, and associates it with the model entry.
The model entry in the inventory can now be moved to an In progress state and stakeholders can review the assets for the entry, which now include the model.
As the model advances in the lifecyle, the model entry will reflect all updates, including deployments and input data assets.
If the data scientist chooses, challenger models can be added to the entry to compare performance.
Validators and other stakeholders can review this and other model entries to ensure compliance with corporate protocols and to view and certify model progress from development to production.

External Models

You can add a model entry for a model that you trained outside of Watson Studio to the model inventory so that you can track the lifecycle details for the model.

The process to track external models is as follows:

A user with Admin access to the IBM Knowledge Catalog must first set up a Platform Assets Catalog for registering external models, then enable tracking for external models in the model inventory.
In the model notebook, use the API to define an external model asset to the Platform assets catalog.
Associate the external model asset with a model entry in the model inventory to start preserving the facts.

Related API

Collect model training metrics automatically during model development in Notebooks. Using the AI Gov Facts Client Library, a model developer can enable collection of a rich set of model metrics, parameters and tags during training.

Report Template API

Generate a printer-friendly document that contains all the information about a model that can be exported to PDF via browser print.

AI Factsheets API | IBM Cloud API Docs