IBM Cloud API Docs

Introduction

Watson 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:

  1. Log in to IBM Cloud and select Manage > Security > Platform API Keys.
  2. 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.
  3. 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
        }
  1. 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:

  1. 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.

Security scheme

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

BearerToken

Value
  • HTTP
  • Bearer
  • JWT

BasicAuth

Value
  • HTTP
  • Basic

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 Watson 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 Watson 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.

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.

Methods

Get all Factsheet service configuration settings

Get all Factsheet service configuration settings

GET /v1/aigov/factsheet/settings

Authentication

This method uses the following security schemes for authentication.

Request

Query Parameters

  • call_ref optional for caller reference

Response

Status Code

  • Settings retrieved successfully

  • Bad request

  • Unauthorized

  • AI Factsheets Service is not available now please try after some time

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get Factsheet service configuration setting

Get Factsheet service configuration setting

GET /v1/aigov/factsheet/settings/{setting}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Setting name

Query Parameters

  • call_ref optional for caller reference

Response

Status Code

  • Setting retrieved successfully

  • Bad request

  • Unauthorized

  • AI Factsheets Service is not available now please try after some time

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete the Factsheet service configuration setting

Delete the Factsheet service configuration setting

DELETE /v1/aigov/factsheet/settings/{setting}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Setting name

Query Parameters

  • call_ref optional for caller reference

Response

Status Code

  • Setting deleted successfully

  • Bad request

  • Unauthorized

  • AI Factsheets Service is not available now please try after some time

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Add or Update the Factsheet service configuration setting

Add or Update the Factsheet service configuration setting

PUT /v1/aigov/factsheet/settings/{setting}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Setting name

Query Parameters

  • call_ref optional for caller reference

Setting value

Response

Status Code

  • Setting added or updated

  • Setting added or updated

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get All WKC Model Entry assets

Returns all WKC Model Entry assets

GET /v1/aigov/model_inventory/model_entries

Authentication

This method uses the following security schemes for authentication.

Request

Query Parameters

  • Account ID. Limited to use by accredited services. Must be supplied when caller is an accredited service. Used for listing catalogs, projects, or spaces for the account or for retrieving the number of public catalogs for the account.

    Possible values: Value must match regular expression ^[0-9a-f]{3}$|^[0-9a-f]{32}$

  • call_ref optional for caller reference

Response

Status Code

  • Get All WKC Model Entry assets successful

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Create a WKC Model Entry asset for given catalog

Creates an asset of Type Model Entry

POST /v1/aigov/model_inventory/model_entries

Authentication

This method uses the following security schemes for authentication.

Request

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

ModelEntry attributes

Response

Status Code

  • WKC Model Entry asset created

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Fetch WKC Model Entry Asset for given assetId

Returns WKC Model Entry Asset for given assetId

GET /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntry Asset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • Fetch WKC Model Entry Asset for given assetId successful

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete Model Entry

Use this API to delete an existing model entry and remove model entry information

DELETE /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntryAsset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • No Content

  • Bad request

  • Unauthorized

  • Forbidden.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update Status value of ModelEntry

Updates Status value of ModelEntry

PATCH /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntry Asset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

ModelEntryStatus Schema

Response

Status Code

  • Created

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Fetch all Physical Models for a logical Model

Returns all Physical Models for a logical Model

GET /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/models

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntryAsset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • Fetch all Physical Models for a logical Model

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Fetch Alerts for given Model Entry Asset

Returns Alerts for given Model Entry Asset

GET /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/alerts

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntry Asset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • Deployment GUID

  • call_ref optional for caller reference

Response

Status Code

  • Fetch Alerts for given Model Entry Asset successful

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update master_id for a model

Updates master_id of model

PATCH /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/relatemodels

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • ModelEntry Asset GUID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Notebook experiment

Response

Status Code

  • Created

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Save External Model

Creates or updates an asset of type Model Stub

PUT /v1/aigov/model_inventory/model_stub

Authentication

This method uses the following security schemes for authentication.

Request

Query Parameters

  • Experiment Name

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

ModelStub metadata

Response

Status Code

  • Created

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Link Model to Model Entry

Link Model to Model Entry

POST /v1/aigov/model_inventory/models/{asset_id}/model_entry

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Asset GUID

Query Parameters

  • You must provide either a catalog id, a project id, or a space id, but not more than one

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • call_ref optional for caller reference

ModelEntryDetails Schema

Response

Status Code

  • Created

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Unlink Model to Model Entry

Unlink Model to Model Entry

DELETE /v1/aigov/model_inventory/models/{asset_id}/model_entry

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Asset GUID

Query Parameters

  • You must provide either a catalog id, a project id, or a space id, but not more than one

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • call_ref optional for caller reference

Response

Status Code

  • No Content

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Fetch System facts of the Model

Returns System Facts of the Model

GET /v1/aigov/model_inventory/models/{asset_id}/system_facts

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Asset GUID

Query Parameters

  • You must provide either a catalog id, a project id, or a space id, but not more than one

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • call_ref optional for caller reference

Response

Status Code

  • Fetch all WKC Model Entry assets for the catalog

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Gets the version details of a model

Gets the version details of a model

GET /v1/aigov/model_inventory/models/{model_asset_id}/version_details

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model Asset ID

Query Parameters

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • You must provide either a catalog id, a project id, or a space id, but not more than one

  • call_ref optional for caller reference

Response

Status Code

  • Returns version details for a model in a given catalog or project or space

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Create approach for model use case

Create approach for model use case

POST /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/version_approach

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model use case ID

Query Parameters

  • You must provide catalog id under which this model use case is present

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Approach data

Response

Status Code

  • Approach created

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete approach from model use case

Delete model use case approach

DELETE /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/version_approach/{approach_id}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model use case ID

  • Approach ID

Query Parameters

  • You must provide catalog id under which this model use case is present

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • Approach deleted

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update model use case approach

Update model use case approach

PATCH /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/version_approach/{approach_id}

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model use case ID

  • Approach ID

Query Parameters

  • You must provide catalog id under which this model use case is present

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Patch array e.g [{"op":"add","path":"/name","value": "string"},{"op":"add","path":"/description","value": "string"}]

Response

Status Code

  • Approach deleted

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get approaches and versions of all tracked models of a model use case

Get approaches and versions of all tracked models of a model use case

GET /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/tracked_model_versions

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model use case ID

Query Parameters

  • You must provide catalog id under which this model use case is present

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • Fetch model use case approaches

  • Bad request

  • Unauthorized

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

List all deployments of external model

List all deployments of external model

GET /v1/aigov/model_inventory/models/{model_asset_id}/deployments

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model Asset ID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Response

Status Code

  • Returns all deployments of external model for a given assetId and catalog

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Add a deployment to External Model

Adds a deployment to External Model

PUT /v1/aigov/model_inventory/models/{model_asset_id}/deployments

Authentication

This method uses the following security schemes for authentication.

Request

Path Parameters

  • Model Asset ID

Query Parameters

  • Catalog GUID

    Possible values: Value must match regular expression ^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$

  • call_ref optional for caller reference

Deployment details data

Response

Status Code

  • Created

  • Bad request

  • Unauthorized

  • Forbidden

  • Requested data are not available, try again later.

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

</