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.
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_tokenproperty for your Factsheet API calls. Set theaccess_tokenvalue as the authorization header parameter for requests to the Watson Data APIs. The format isAuthorization: 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
Bearerfrom 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.
Methods
Add or Update the Factsheet service configuration setting
Add or Update the Factsheet service configuration setting
PUT /v1/aigov/factsheet/settings/{setting}Get All WKC Model Entry assets
Returns all WKC Model Entry assets
GET /v1/aigov/model_inventory/model_entries
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
Create a WKC Model Entry asset for given catalog
Creates an asset of Type Model Entry
POST /v1/aigov/model_inventory/model_entries
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
- metadata
- usage
- rov
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$
- entity
Model Entry asset URL
Model Entry asset id
Status Code
WKC Model Entry asset created
Bad request
Unauthorized
Requested data are not available, try again later.
Internal Server Error
No Sample Response
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}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
- metadata
- usage
- rov
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$
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
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}Update Status value of ModelEntry
Updates Status value of ModelEntry
PATCH /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}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}/modelsFetch Alerts for given Model Entry Asset
Returns Alerts for given Model Entry Asset
GET /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/alertsUpdate master_id for a model
Updates master_id of model
PATCH /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/relatemodelsSave External Model
Creates or updates an asset of type Model Stub
PUT /v1/aigov/model_inventory/model_stub
Link Model to Model Entry
Link Model to Model Entry
POST /v1/aigov/model_inventory/models/{asset_id}/model_entryRequest
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
- version_details
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$
Response
Catalog ID of the model entry asset
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Asset ID of the model entry
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Model Entry Name
Model Entry Status
Model version number
Model version comment
Model approach name
Status Code
Created
Bad request
Unauthorized
Forbidden
Requested data are not available, try again later.
Internal Server Error
No Sample Response
Unlink Model to Model Entry
Unlink Model to Model Entry
DELETE /v1/aigov/model_inventory/models/{asset_id}/model_entryRequest
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
Fetch System facts of the Model
Returns System Facts of the Model
GET /v1/aigov/model_inventory/models/{asset_id}/system_factsRequest
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
- model_information
- training_information
- modelentry_information
- model_identity_information
- space_details
- openpages_details
- deployment_details
- schemas
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
Gets the version details of a model
Gets the version details of a model
GET /v1/aigov/model_inventory/models/{model_asset_id}/version_detailsRequest
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
Create approach for model use case
Create approach for model use case
POST /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/version_approachRequest
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
Default:
New approachDefault:
Your model will be tracked under this approach.Allowable values: [
Packages,Sprout,Tree,Neural_network,Rocket,Linear,Logistic,Decision_tree,Support_vector_machines,Network,Unrelated,Dimensions,Bot,Image,Scale,Finance,Piggy_bank,Delivery,Factory,Electronics,Idea,Globe,Recycle,Gift,Zombie]Allowable values: [
Gray,Green,Teal,Cyan,Blue,Purple,Magenta,Red,Orange,Yellow]
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}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}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"}]
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_versionsList all deployments of external model
List all deployments of external model
GET /v1/aigov/model_inventory/models/{model_asset_id}/deploymentsAdd a deployment to External Model
Adds a deployment to External Model
PUT /v1/aigov/model_inventory/models/{model_asset_id}/deploymentsDelete deployment of an external model.
Delete deployment of an external model.
NOTE: This feature works only for External Models.
DELETE /v1/aigov/model_inventory/models/{model_asset_id}/deployments/{deployment_id}Move deployment from source to target environment
Move deployment from source to target environment
PUT /v1/aigov/model_inventory/models/{model_asset_id}/deployments/{deployment_id}/environmentRequest
Path Parameters
Model Asset ID
Model Deployment 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
Target environment value is case sensitive and should match one of these options [Test, Validate, Operate]
Allowable values: [
Test,Validate,Operate]
Move model from source to target environment
Move model from source to target environment
PUT /v1/aigov/model_inventory/models/{model_asset_id}/environmentRequest
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
Target environment value is case sensitive and should match one of these options [Develop, Test, Validate, Operate]
Allowable values: [
Develop,Test,Validate,Operate]
Modify the approach or version or both of all tracked models that belong to the given version number and approach
Modify the approach or version or both of all tracked models that belong to the given version number and approach
PUT /v1/aigov/model_inventory/model_usecases/{model_usecase_asset_id}/version_approach/{approach_id}/versions/{version_number}Request
Path Parameters
Model use case ID
Approach ID
Version Number
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
Target approach id, number, and comment
Download Model Entry report
Returns 200 OK status with specified model entry report to download. Otherwise, 500 Internal Server Error
GET /v1/aigov/model_inventory/model_entries/{model_entry_asset_id}/reportDownload model report
Returns 200 OK status with specified model report to download. Otherwise, 500 Internal Server Error
GET /v1/aigov/model_inventory/models/{asset_id}/reportRequest
Path Parameters
Asset GUID
Query Parameters
Template GUID
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
File Format
Allowable values: [
html,pdf,docx]Ignore errors
call_ref optional for caller reference
Get report templates detail
Returns list of all the temnplates detail
GET /v1/aigov/report_templates
Update report template
Update report template with ftl file to be used for report generation
PATCH /v1/aigov/report_templates/{template_id}Update specific report template file content
Updates specified template id with template file name and content
POST /v1/aigov/report_templates/{template_id}/content