factsheets service has 3 resource kinds, each listed below with its endpoints, fields, and dependencies. Values resolve late, so you reference another resource with ${kind.ref_name}. For defaults, validation rules, and examples, run wxctl explain <kind>.
YAML envelope & reference syntax
YAML envelope & reference syntax
- Envelope: A config is one or more YAML documents separated by
---. Each has top-levelkindandref_name, then the fields below at the top level (not nested underspec). ref_name: Unique handle for this resource within the config. Used to reference it from other resources, then stripped before the API call (not a schema field).- References: Reference another resource by its ref_name:
${<kind>.<ref_name>}resolves to its id,${<kind>.<ref_name>.<field>}to a specific field. Values resolve late, at plan/apply time.
inventory
An inventory is an AI Factsheets model inventory: a governance catalog that holds the model use cases tracked for an organization.
Runs on SaaS + Software · ID field guid
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/aigov/inventories |
| Read | GET | /v1/aigov/inventories/{guid} |
| List | GET | /v1/aigov/inventories |
| Update | PATCH | /v1/aigov/inventories/{guid} |
| Delete | DELETE | /v1/aigov/inventories/{guid}?delete_bucket=true |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Inventory (catalog) display name. |
description | string | Optional | Inventory description. |
generator | string | Optional | Identifier of the component that generated the inventory. The factsheets create forwards this to the underlying /v2/catalogs API, which REQUIRES it (“Catalog Generator”) even though the inventories OpenAPI marks it optional, so it defaults to ‘wxctl’ (mirrors the catalog kind’s generator field). |
bss_account_id | string | Optional | Account scoping, sent on create, not part of drift state. |
is_governed | boolean | Optional | Whether the inventory enforces governance. |
bucket | object | Required | COS bucket backing the inventory catalog. The factsheets create forwards this to the underlying /v2/catalogs API, which REQUIRES it (“BUCSV3009E: Bucket must be Provided”) even though the inventories OpenAPI marks it optional. ‘assetfiles’ is the platform-managed internal store, needing only a bucket_name and no external credentials (mirrors the catalog kind’s bucket). Create-time input, excluded from state_fields, so it is not part of drift comparison. |
metadata, entity, guid.
Consumers
model_entry→.catalog_id(required)model_tracking→.catalog_id(optional)model_tracking→.model_entry_catalog_id(optional)
model_entry
A model entry is an AI Factsheets model use case that groups the tracked models, deployments, and factsheets for one business problem within a model inventory.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/aigov/model_inventory/model_entries |
| Read | GET | /v1/aigov/model_inventory/model_entries/{asset_id} |
| List | GET | /v1/aigov/model_inventory/model_entries |
| Update | PATCH | /v1/aigov/model_inventory/model_entries/{asset_id} |
| Delete | DELETE | /v1/aigov/model_inventory/model_entries/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
catalog_id | string | Required | GUID of the inventory/catalog this model use case belongs to. The factsheets model_entries API requires it as a query parameter on EVERY operation (create, get, update, delete), not just create, so it is modelled as location: Query (appended to all requests) rather than a create-only body field. |
name | string | Required | Display name of the model entry / AI use case. |
description | string | Optional | Description of the model entry. |
metadata, entity, href.
Depends on
catalog_id→inventory(required)
model_tracking→.model_entry(required)
model_tracking
Associates a trained Watson Machine Learning model (incl. AutoAI) with a governance model_entry (AI use case) so the model is tracked in a model inventory.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/aigov/model_inventory/models/{model}/model_entry |
| Read | GET | /v1/aigov/model_inventory/models/{model}/model_entry |
| Delete | DELETE | /v1/aigov/model_inventory/models/{model}/model_entry |
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Required | WML model asset id to track. Fills the {model} path segment. References wml_model.id → DAG edge so tracking runs after the model. also_allows wml_function (a stored deployable function) and asset_promotion (track the project-side model via ${asset_promotion.x.source_asset_id} in the develop stage; mirrors wml_deployment.asset). |
model_entry | string | Required | Target model_entry (AI use case) asset id. Sent in the create body as model_entry_asset_id. References model_entry.asset_id → DAG edge. |
model_entry_catalog_id | string | Required | Catalog/inventory the model_entry lives in. Sent in the create body and used as the required catalog_id query on the existence-check GET. References inventory.guid; reference is optional so SaaS can pass ${env:WXCTL_INVENTORY_ID} (no inventory resource). |
space_id | string | Optional | Deployment space the MODEL lives in (one of space_id/project_id/catalog_id). |
project_id | string | Optional | Project the MODEL lives in (alt scope). |
catalog_id | string | Optional | Catalog the MODEL lives in (alt scope). Distinct from model_entry_catalog_id (where the use case lives). |
version_number | string | Optional | Tracked version number. The API requires a number; defaults to 1.0.0. |
version_comment | string | Optional | Optional version comment. |
approach_id | string | Optional | Optional approach id; omit to use the use case’s default approach. |
id.
Depends on
model→wml_model(required)model→wml_function(optional)model→asset_promotion(optional)model_entry→model_entry(required)model_entry_catalog_id→inventory(optional)space_id→space(optional)project_id→project(optional)catalog_id→inventory(optional)